# Requiems API — Full Documentation

> Requiems is a unified API platform providing instant access to production-ready APIs for text utilities, email validation, entertainment data, geographic information, and more. All APIs are accessible with a single API key.

**Base URL:** `https://requiems.xyz`
**Authentication:** `requiems-api-key` header

---
# Exchange Rate

Get live currency exchange rates and convert amounts between currencies. Rates are sourced from the European Central Bank via Frankfurter and cached for up to one hour.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 817 ms |
| p95 | 921 ms |
| p99 | 1022 ms |

## `GET /v1/finance/exchange-rate`

Returns the current exchange rate between two currencies.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | ISO 4217 source currency code (3 letters, e.g. USD) |
| `to` | string | Yes | ISO 4217 target currency code (3 letters, e.g. EUR) |

### Response Example

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "rate": 0.92,
    "timestamp": "2024-12-15T00:00:00Z"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | Source currency code (uppercased) |
| `to` | string | Target currency code (uppercased) |
| `rate` | number | Exchange rate — how many units of `to` equal 1 unit of `from` |
| `timestamp` | string | Date the rate was published by the ECB (ISO 8601) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | A required parameter is missing or the currency code is not exactly 3 alphabetic characters. |
| `invalid_currency` | 422 | One or both currency codes are not recognised by the upstream data source. |
| `upstream_error` | 503 | The exchange rate data source is temporarily unavailable. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/exchange-rate?from=USD&to=EUR" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/exchange-rate"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"from": "USD", "to": "EUR"}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]
print(data["rate"])  # 0.92
```

**Javascript**

```javascript
const params = new URLSearchParams({ from: 'USD', to: 'EUR' });
const response = await fetch(
  `https://requiems.xyz/v1/finance/exchange-rate?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.rate);  // 0.92
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/exchange-rate')
uri.query = URI.encode_www_form(from: 'USD', to: 'EUR')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['rate']  # 0.92
```

## `GET /v1/finance/convert`

Converts an amount from one currency to another and returns the rate alongside the converted value.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | ISO 4217 source currency code (3 letters, e.g. USD) |
| `to` | string | Yes | ISO 4217 target currency code (3 letters, e.g. EUR) |
| `amount` | number | Yes | Amount to convert. Must be greater than 0. |

### Response Example

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "rate": 0.92,
    "amount": 100,
    "converted": 92.00,
    "timestamp": "2024-12-15T00:00:00Z"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | Source currency code (uppercased) |
| `to` | string | Target currency code (uppercased) |
| `rate` | number | Exchange rate used for the conversion |
| `amount` | number | The original amount passed in the request |
| `converted` | number | Result of amount × rate, rounded to 2 decimal places |
| `timestamp` | string | Date the rate was published by the ECB (ISO 8601) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | A required parameter is missing, the currency code is not 3 alphabetic characters, or the amount is 0 or negative. |
| `invalid_currency` | 422 | One or both currency codes are not recognised by the upstream data source. |
| `upstream_error` | 503 | The exchange rate data source is temporarily unavailable. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/convert?from=USD&to=EUR&amount=100" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/convert"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"from": "USD", "to": "EUR", "amount": 100}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]
print(data["converted"])  # 92.0
print(data["rate"])       # 0.92
```

**Javascript**

```javascript
const params = new URLSearchParams({ from: 'USD', to: 'EUR', amount: 100 });
const response = await fetch(
  `https://requiems.xyz/v1/finance/convert?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.converted);  // 92
console.log(data.rate);       // 0.92
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/convert')
uri.query = URI.encode_www_form(from: 'USD', to: 'EUR', amount: 100)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['converted']  # 92.0
puts data['rate']       # 0.92
```

---
# Crypto Prices

Get live cryptocurrency prices, 24-hour change, market cap, and trading volume for 20+ major coins. Prices are sourced from CoinGecko and cached for up to 5 minutes.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 813 ms |
| p95 | 1021 ms |
| p99 | 1214 ms |

## `GET /v1/finance/crypto/{symbol}`

Returns current price data for the given cryptocurrency symbol.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `symbol` | string | Yes | Uppercase ticker symbol (e.g. BTC, ETH, SOL) |

### Response Example

```json
{
  "data": {
    "symbol": "BTC",
    "name": "Bitcoin",
    "price_usd": 42000.50,
    "change_24h": 2.5,
    "market_cap": 820000000000,
    "volume_24h": 25000000000
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `symbol` | string | Uppercase ticker symbol |
| `name` | string | Full coin name |
| `price_usd` | number | Current price in USD |
| `change_24h` | number | Price change over the last 24 hours as a percentage |
| `market_cap` | number | Total market capitalisation in USD |
| `volume_24h` | number | Total trading volume over the last 24 hours in USD |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `unknown_symbol` | 422 | The symbol is not in the supported coin list. |
| `upstream_error` | 503 | CoinGecko is unavailable or returned an unexpected response. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/finance/crypto/BTC \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/crypto/BTC"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()["data"]
print(f"{data['name']}: ${data['price_usd']:,.2f}")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/finance/crypto/BTC', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const { data } = await response.json();
console.log(`${data.name}: $${data.price_usd.toLocaleString()}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/crypto/BTC')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "#{data['name']}: $#{data['price_usd']}"
```

---
# BIN Lookup

Look up card metadata for any Bank Identification Number — scheme, card type, issuing bank, country, and more.

**Base URL:** `https://requiems.xyz`

## `GET /v1/finance/bin/{bin}`

Returns card metadata for the given 6–8 digit BIN prefix.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `bin` | string | Yes | 6–8 digit Bank Identification Number. Dashes and spaces are stripped automatically. |

### Response Example

```json
{
  "data": {
    "bin": "424242",
    "scheme": "visa",
    "card_type": "credit",
    "card_level": "classic",
    "issuer_name": "Chase",
    "issuer_url": "www.chase.com",
    "issuer_phone": "+18002324000",
    "country_code": "US",
    "country_name": "United States",
    "prepaid": false,
    "luhn_prefix_valid": true,
    "confidence": 0.92
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `bin` | string | The normalised BIN prefix used for the lookup |
| `scheme` | string | Card network: visa, mastercard, amex, discover, jcb, diners, unionpay, maestro, mir, rupay, private_label |
| `card_type` | string | credit, debit, prepaid, or charge |
| `card_level` | string | classic, gold, platinum, infinite, business, signature, or standard |
| `issuer_name` | string | Name of the card-issuing bank |
| `issuer_url` | string | Bank website URL |
| `issuer_phone` | string | Bank customer service phone number |
| `country_code` | string | ISO 3166-1 alpha-2 country code of the issuing bank (e.g. US, GB, DE) |
| `country_name` | string | Full country name of the issuing bank |
| `prepaid` | boolean | Whether the card is a prepaid card |
| `luhn_prefix_valid` | boolean | Whether the BIN prefix (not a full card number) passes the Luhn algorithm check |
| `confidence` | number | Data quality score (0.00–1.00). Multi-source confirmed records score higher. |
| `data_freshness` | string | Year and month the underlying BIN data was last refreshed (YYYY-MM), based on the most recent seed run for this record |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | BIN is not 6–8 digits or contains non-digit characters. |
| `not_found` | 404 | BIN prefix not found in the database. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/finance/bin/424242 \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/bin/424242"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data["data"]["scheme"])        # "visa"
print(data["data"]["issuer_name"])   # "Chase"
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/finance/bin/424242', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(data.scheme);       // "visa"
console.log(data.issuer_name);  // "Chase"
console.log(data.country_code); // "US"
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/bin/424242')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['scheme']       # "visa"
puts data['issuer_name']  # "Chase"
```

---
# IBAN Validator

Validate IBAN numbers and extract the bank code and account number. Supports all countries in the official SWIFT IBAN Registry. Returns a structured response for both valid and invalid IBANs — the valid field tells you whether the IBAN passed checksum validation.

**Base URL:** `https://requiems.xyz`

## `GET /v1/finance/iban/{iban}`

Validates an IBAN and returns the country, bank code, and account number. Spaces in the input are stripped automatically. Always returns HTTP 200 — check the valid field to determine whether the IBAN is valid.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `iban` | string | Yes | The IBAN to validate. Spaces are stripped. Case-insensitive. |

### Response Example

```json
{
  "data": {
    "iban": "DE89370400440532013000",
    "valid": true,
    "country": "Germany",
    "bank_code": "37040044",
    "account": "0532013000"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `iban` | string | The normalised IBAN (spaces stripped, uppercased) |
| `valid` | boolean | true if the IBAN passed length and ISO 13616 checksum validation |
| `country` | string | Full country name (empty if the country code is not in the registry) |
| `bank_code` | string | Bank identifier extracted from the BBAN (empty if country not in registry or positions not defined) |
| `account` | string | Account number extracted from the BBAN (empty if country not in registry or positions not defined) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error (e.g. database unreachable). |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/iban/DE89370400440532013000" \
  -H "requiems-api-key: YOUR_API_KEY"

# With spaces (URL-encoded):
curl "https://requiems.xyz/v1/finance/iban/DE89%203704%200044%200532%200130%2000" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

iban = "DE89370400440532013000"
url = f"https://requiems.xyz/v1/finance/iban/{iban}"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()["data"]

if data["valid"]:
    print(f"Country:   {data['country']}")
    print(f"Bank code: {data['bank_code']}")
    print(f"Account:   {data['account']}")
else:
    print("Invalid IBAN")
```

**Javascript**

```javascript
const iban = "DE89370400440532013000";
const response = await fetch(
  `https://requiems.xyz/v1/finance/iban/${iban}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();

if (data.valid) {
  console.log(`Country:   ${data.country}`);
  console.log(`Bank code: ${data.bank_code}`);
  console.log(`Account:   ${data.account}`);
} else {
  console.log('Invalid IBAN');
}
```

**Ruby**

```ruby
require 'net/http'
require 'json'

iban = "DE89370400440532013000"
uri = URI("https://requiems.xyz/v1/finance/iban/#{iban}")

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
if data['valid']
  puts "Country:   #{data['country']}"
  puts "Bank code: #{data['bank_code']}"
  puts "Account:   #{data['account']}"
else
  puts "Invalid IBAN"
end
```

## `POST /v1/finance/iban/batch`

Validates up to 50 iban numbers in a single request. Results are returned in the same order as the input.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `numbers` | array<string> | Yes | Array of iban numbers to validate (min: 1, max: 50). |

### Request

```json
{
  "numbers": ["GB29NWBK60161331926819", "DE89370400440532013000", "XX89370400440532013000"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "iban": "GB29NWBK60161331926819",
        "valid": true,
        "country": "United Kingdom",
        "bank_code": "NWBK",
        "account": "31926819"
      },
      {
        "iban": "DE89370400440532013000",
        "valid": true,
        "country": "Germany",
        "bank_code": "37040044",
        "account": "0532013000"
      },
      {
        "iban": "XX89370400440532013000",
        "valid": false,
        "country": "",
        "bank_code": "",
        "account": ""
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-05-03T19:25:02Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Validation result for each number in the same order as the input. Each item has the same fields as the single validate endpoint. |
| `total` | integer | Number of results returned. Matches the length of the input array. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The numbers array is missing, empty, or contains more than 50 items. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/finance/iban/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["GB29NWBK60161331926819","DE89370400440532013000"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/iban/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"numbers": ["GB29NWBK60161331926819", "DE89370400440532013000"]}

response = requests.post(url, headers=headers, json=payload)
for result in response.json()["data"]["results"]:
    print(result["iban"], result["valid"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/finance/iban/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ numbers: ['GB29NWBK60161331926819', 'DE89370400440532013000'] })
  }
);

const { data } = await response.json();
data.results.forEach(r => console.log(r.iban, r.valid));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/iban/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { numbers: ['GB29NWBK60161331926819', 'DE89370400440532013000'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |r|
  puts "#{r['iban']}: #{r['valid']}"
end
```

---
# SWIFT Code

Validate and look up bank information by SWIFT/BIC code. Returns bank name, city, country, and parsed code components.

**Base URL:** `https://requiems.xyz`

## `GET /v1/finance/swift/{code}`

Look up bank metadata for a SWIFT/BIC code.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | SWIFT/BIC code (8 or 11 alphanumeric characters) |

### Response Example

```json
{
  "data": {
    "swift_code": "DEUTDEDBXXX",
    "bank_code": "DEUT",
    "country_code": "DE",
    "location_code": "DB",
    "branch_code": "XXX",
    "bank_name": "Deutsche Bank AG",
    "city": "Frankfurt am Main",
    "country_name": "Germany",
    "is_primary": true
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `swift_code` | string | Full 11-character SWIFT/BIC code |
| `bank_code` | string | Institution code (characters 1-4) |
| `country_code` | string | ISO 3166-1 alpha-2 country code (characters 5-6) |
| `location_code` | string | Location code (characters 7-8) |
| `branch_code` | string | Branch code (characters 9-11), XXX for primary office |
| `bank_name` | string | Bank or institution name |
| `city` | string | City of the branch or primary office |
| `country_name` | string | Full country name |
| `is_primary` | boolean | true when branch_code is XXX |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | Invalid SWIFT/BIC format (must be 8 or 11 valid characters). |
| `not_found` | 404 | SWIFT/BIC code not found in the dataset. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/swift/DEUTDEDB" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/swift/DEUTDEDB"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json()["data"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/finance/swift/DEUTDEDB', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/swift/DEUTDEDB')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']
```

## `GET /v1/finance/swift`

List SWIFT records with optional filters and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `country_code` | string | No | Optional 2-letter country code filter (e.g. DE, US) |
| `bank_code` | string | No | Optional 4-letter bank code filter (e.g. DEUT) |
| `q` | string | No | Optional text search across swift_code, bank_name, and city |
| `limit` | integer | No | Max rows to return (default 50, max 200) |
| `offset` | integer | No | Number of rows to skip (default 0) |

### Response Example

```json
{
  "data": {
    "items": [
      {
        "swift_code": "DEUTDEDBXXX",
        "bank_code": "DEUT",
        "country_code": "DE",
        "location_code": "DB",
        "branch_code": "XXX",
        "bank_name": "Deutsche Bank Privat-Und Geschaeftskunden Ag - Head Office",
        "city": "Frankfurt Am Main",
        "country_name": "Germany",
        "is_primary": true
      }
    ],
    "limit": 50,
    "offset": 0,
    "returned": 1
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | Invalid filter or pagination parameter. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/finance/swift/DEUTDEDB \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

code = "DEUTDEDB"
url = f"https://requiems.xyz/v1/finance/swift/{code}"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()["data"]

print(data["swift_code"])
print(data["bank_name"])
print(data["country_name"])
```

**Javascript**

```javascript
const code = 'DEUTDEDB';
const response = await fetch(`https://requiems.xyz/v1/finance/swift/${code}`, {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(data.swift_code);
console.log(data.bank_name);
console.log(data.country_name);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

code = 'DEUTDEDB'
uri = URI("https://requiems.xyz/v1/finance/swift/#{code}")
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['swift_code']
puts data['bank_name']
puts data['country_name']
```

---
# Mortgage Calculator

Calculate monthly mortgage payments and generate a full amortization schedule for any fixed-rate loan. Returns the monthly payment, total cost, total interest, and a month-by-month breakdown.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 825 ms |
| p95 | 1196 ms |
| p99 | 1287 ms |

## `GET /v1/finance/mortgage`

Returns the monthly payment, total cost, and full amortization schedule for a fixed-rate mortgage.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `principal` | number | Yes | Loan amount in your chosen currency (e.g. 300000 for $300,000) |
| `rate` | number | Yes | Annual interest rate as a percentage (e.g. 6.5 for 6.5%). Must be greater than 0. |
| `years` | integer | Yes | Loan term in years (1–50) |

### Response Example

```json
{
  "data": {
    "principal": 300000,
    "rate": 6.5,
    "years": 30,
    "monthly_payment": 1896.2,
    "total_payment": 682632.0,
    "total_interest": 382632.0,
    "schedule": [
      {
        "month": 1,
        "payment": 1896.2,
        "principal": 271.2,
        "interest": 1625.0,
        "balance": 299728.8
      },
      {
        "month": 2,
        "payment": 1896.2,
        "principal": 272.67,
        "interest": 1623.53,
        "balance": 299456.13
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `principal` | number | The original loan amount passed in the request |
| `rate` | number | The annual interest rate passed in the request |
| `years` | integer | The loan term in years passed in the request |
| `monthly_payment` | number | Fixed monthly payment amount (rounded to 2 decimal places) |
| `total_payment` | number | Total amount paid over the life of the loan |
| `total_interest` | number | Total interest paid (total_payment minus principal) |
| `schedule` | array<object> | Full amortization schedule — one entry per month (years × 12 entries) |
| `schedule[].month` | integer | Month number (1 to years × 12) |
| `schedule[].payment` | number | Total payment for this month |
| `schedule[].principal` | number | Portion of this month's payment applied to principal |
| `schedule[].interest` | number | Portion of this month's payment applied to interest |
| `schedule[].balance` | number | Remaining loan balance after this payment |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | A required parameter is missing, not a valid number, or out of range (e.g. years > 50 or rate <= 0). |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/mortgage?principal=300000&rate=6.5&years=30" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/mortgage"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"principal": 300000, "rate": 6.5, "years": 30}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]
print(data["monthly_payment"])  # 1896.2
print(data["total_interest"])   # 382632.0
print(len(data["schedule"]))    # 360
```

**Javascript**

```javascript
const params = new URLSearchParams({ principal: 300000, rate: 6.5, years: 30 });
const response = await fetch(
  `https://requiems.xyz/v1/finance/mortgage?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.monthly_payment);  // 1896.2
console.log(data.total_interest);   // 382632.0
console.log(data.schedule.length);  // 360
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/mortgage')
uri.query = URI.encode_www_form(principal: 300000, rate: 6.5, years: 30)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['monthly_payment']  # 1896.2
puts data['total_interest']   # 382632.0
```

## `POST /v1/finance/mortgage/batch`

Calculate up to 50 mortgages in a single request. Results are returned in the same order as the input.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mortgages` | array<object> | Yes | Array of mortgages to calculate (min: 1, max: 50). |

### Request

```json
{
  "mortgages": [
    {
      "principal": 150000,
      "rate": 6.5,
      "years": 10
    },
    {
      "principal": 250000,
      "rate": 5.2,
      "years": 30
    }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "principal": 150000,
        "rate": 6.5,
        "years": 10,
        "monthly_payment": 1703.22,
        "total_payment": 204386.36,
        "total_interest": 54386.36,
        "schedule": [
          {
            "month": 1,
            "payment": 1703.22,
            "principal": 890.72,
            "interest": 812.5,
            "balance": 149109.28
          },
          {
            "month": 2,
            "payment": 1703.22,
            "principal": 895.54,
            "interest": 807.68,
            "balance": 148213.74
          }
        ]
      },
      {
        "principal": 250000,
        "rate": 5.2,
        "years": 30,
        "monthly_payment": 1372.78,
        "total_payment": 494199.79,
        "total_interest": 244199.79,
        "schedule": [
          {
            "month": 1,
            "payment": 1372.78,
            "principal": 289.44,
            "interest": 1083.33,
            "balance": 249710.56
          },
          {
            "month": 2,
            "payment": 1372.78,
            "principal": 290.7,
            "interest": 1082.08,
            "balance": 249419.86
          }
        ]
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-05-10T19:20:02Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Mortgage calculation result for each mortgage request in the same order as the input. Each item has the same fields as the single mortgage endpoint. |
| `total` | integer | Number of results returned. Matches the length of the input array. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The mortgages array is missing, empty, or contains more than 50 items. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/finance/mortgage/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mortgages":[{"principal": 150000,"rate": 6.5,"years": 10},{"principal": 250000,"rate": 5.2,"years": 30}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/mortgage/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"mortgages":[{"principal": 150000,"rate": 6.5,"years": 10},{"principal": 250000,"rate": 5.2,"years": 30}]}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/finance/mortgage/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ mortgages: [{"principal": 150000,"rate": 6.5,"years": 10},{"principal": 250000,"rate": 5.2,"years": 30}] })
  }
);

const { data } = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/mortgage/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { mortgages: [{"principal": 150000,"rate": 6.5,"years": 10},{"principal": 250000,"rate": 5.2,"years": 30}] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.pretty_generate(JSON.parse(response.body))
```

---
# Commodity Prices

Historical and current annual average prices for 16 major commodities — precious metals, energy, and agricultural goods. Prices are annual averages sourced from FRED (Federal Reserve Economic Data).

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 827 ms |
| p95 | 980 ms |
| p99 | 1066 ms |

## `GET /v1/finance/commodities/{commodity}`

Returns the latest annual average price and up to 10 years of historical data for the requested commodity slug.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `commodity` | string | Yes | Commodity slug (e.g. gold, silver, oil). See supported slugs below. |

### Response Example

```json
{
  "data": {
    "commodity": "gold",
    "name": "Gold",
    "price": 2386.3300,
    "unit": "oz",
    "currency": "USD",
    "change_24h": 23.01,
    "historical": [
      { "period": "2023", "price": 1940.5400 },
      { "period": "2022", "price": 1800.1200 },
      { "period": "2021", "price": 1798.5200 },
      { "period": "2020", "price": 1769.6400 },
      { "period": "2019", "price": 1392.6000 },
      { "period": "2018", "price": 1268.9300 },
      { "period": "2017", "price": 1257.1500 },
      { "period": "2016", "price": 1251.6500 },
      { "period": "2015", "price": 1160.0600 },
      { "period": "2014", "price": 1266.4000 }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `commodity` | string | The commodity slug as provided in the request path |
| `name` | string | Human-readable commodity name |
| `price` | number | Latest annual average price in the commodity's display unit |
| `unit` | string | Price unit (oz, barrel, mmbtu, lb, or metric_ton) |
| `currency` | string | Currency code — always USD |
| `change_24h` | number | Year-over-year percentage change from the prior year's annual average (positive = price increased) |
| `historical` | array<object> | Up to 10 prior years of annual average prices, ordered newest to oldest |
| `historical[].period` | string | Year of the historical data point |
| `historical[].price` | number | Annual average price for that year |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No data found for the given commodity slug. Check the supported slugs list. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/commodities/gold" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/commodities/gold"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()["data"]
print(data["price"])      # 2386.33
print(data["change_24h"]) # 23.01
print(data["historical"][0]["period"])  # "2023"
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/finance/commodities/gold',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.price);       // 2386.33
console.log(data.change_24h);  // 23.01
console.log(data.historical.length); // up to 10
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/commodities/gold')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['price']      # 2386.33
puts data['change_24h'] # 23.01
```

---
# Inflation

Historical and current CPI inflation rates for 241 countries, sourced from the World Bank. Returns up to 30 years of annual data per country.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 853 ms |
| p95 | 1365 ms |
| p99 | 1386 ms |

## `GET /v1/finance/inflation`

Returns the latest annual CPI inflation rate for a country plus the previous 10 years of historical data.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `country` | string | Yes | ISO 3166-1 alpha-2 country code (e.g. US, GB, DE). Case-insensitive. |

### Response Example

```json
{
  "data": {
    "country": "US",
    "rate": 2.9495,
    "period": "2024",
    "historical": [
      { "period": "2023", "rate": 4.1163 },
      { "period": "2022", "rate": 8.0028 },
      { "period": "2021", "rate": 4.6979 },
      { "period": "2020", "rate": 1.2336 },
      { "period": "2019", "rate": 1.8122 },
      { "period": "2018", "rate": 2.4426 },
      { "period": "2017", "rate": 2.1301 },
      { "period": "2016", "rate": 1.2616 },
      { "period": "2015", "rate": 0.1186 },
      { "period": "2014", "rate": 1.6222 }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `country` | string | ISO 3166-1 alpha-2 country code, uppercased |
| `rate` | number | Latest annual CPI inflation rate as a percentage (e.g. 2.9495 means 2.9495%) |
| `period` | string | Year of the latest data point (e.g. 2024) |
| `historical` | array<object> | Up to 10 previous years of inflation data, ordered newest to oldest |
| `historical[].period` | string | Year of the historical data point |
| `historical[].rate` | number | Annual CPI inflation rate for that year |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The country parameter is missing or is not a valid ISO 3166-1 alpha-2 code. |
| `not_found` | 404 | No inflation data found for the given country code. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/finance/inflation?country=US" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/inflation"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"country": "US"}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]
print(data["rate"])    # 2.9495
print(data["period"])  # "2024"
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/finance/inflation?country=US',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.rate);    // 2.9495
console.log(data.period);  // "2024"
console.log(data.historical.length); // 10
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/inflation')
uri.query = URI.encode_www_form(country: 'US')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['rate']    # 2.9495
puts data['period']  # "2024"
```

## `POST /v1/finance/inflation/batch`

Returns inflation data for up to 50 countries in a single request. Results are in the same order as the input. Countries with no data return found: false instead of failing the whole request. Billing: 1 credit per country (not per HTTP request).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `countries` | array<string> | Yes | Array of ISO 3166-1 alpha-2 country codes. Min: 1, Max: 50. |

### Response Example

```json
{
  "data": {
    "results": [
      {
        "country": "US",
        "found": true,
        "rate": 2.9495,
        "period": "2024",
        "historical": [
          { "period": "2023", "rate": 4.1163 }
        ]
      },
      {
        "country": "AR",
        "found": true,
        "rate": 211.4,
        "period": "2024",
        "historical": []
      },
      {
        "country": "XX",
        "found": false
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One entry per country, in the same order as the input array |
| `results[].country` | string | ISO 3166-1 alpha-2 country code, uppercased |
| `results[].found` | boolean | false when the country has no data in the World Bank set |
| `results[].rate` | number | Latest CPI inflation rate. Omitted when found: false |
| `results[].period` | string | Year of the latest data point. Omitted when found: false |
| `results[].historical` | array<object> | Up to 10 previous years. Omitted when found: false |
| `total` | integer | Total number of results returned (equals number of countries sent) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Body is invalid: empty array, more than 50 items, or a bad country code. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/finance/inflation/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries": ["US", "AR", "DE"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/finance/inflation/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"countries": ["US", "AR", "DE"]}

response = requests.post(url, headers=headers, json=payload)
results = response.json()["data"]["results"]
for item in results:
    if item["found"]:
        print(f"{item['country']}: {item['rate']}%")
    else:
        print(f"{item['country']}: no data")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/finance/inflation/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ countries: ['US', 'AR', 'DE'] })
  }
);

const { data } = await response.json();
data.results.forEach(item => {
  if (item.found) {
    console.log(`${item.country}: ${item.rate}%`);
  } else {
    console.log(`${item.country}: no data`);
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/finance/inflation/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { countries: ['US', 'AR', 'DE'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

results = JSON.parse(response.body)['data']['results']
results.each do |item|
  if item['found']
    puts "#{item['country']}: #{item['rate']}%"
  else
    puts "#{item['country']}: no data"
  end
end
```

---
# Email Validator

Full email validation in one call. Checks RFC 5322 syntax, performs a live MX record lookup to confirm the domain can receive mail, detects disposable addresses, returns the normalized canonical form, and suggests a correction when the domain looks like a common typo.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 876 ms |
| p95 | 1398 ms |
| p99 | 1573 ms |

## `POST /v1/validation/email`

Validates a single email address and returns a full breakdown of syntax validity, MX record status, disposable domain check, normalized form, and any typo suggestion.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | The email address to validate. |

### Request

```json
{
  "email": "user@gmial.com"
}
```

### Response Example

```json
{
  "data": {
    "email": "user@gmial.com",
    "valid": false,
    "syntax_valid": true,
    "mx_valid": false,
    "disposable": false,
    "normalized": "user@gmial.com",
    "domain": "gmial.com",
    "suggestion": "gmail.com"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `email` | string | The email address exactly as supplied in the request body; null when syntax is invalid |
| `valid` | boolean | Overall validity. True only when the address passes syntax validation and the domain has at least one MX record |
| `syntax_valid` | boolean | Whether the address is syntactically valid according to RFC 5322 |
| `mx_valid` | boolean | Whether the domain has at least one MX record, meaning it can receive email |
| `disposable` | boolean | Whether the address uses a known disposable or temporary email domain |
| `normalized` | string | The canonical form of the address after normalization (lowercase, plus-tag removal, alias-domain resolution). Null when syntax is invalid |
| `domain` | string | The domain part of the address (after @). Null when syntax is invalid |
| `suggestion` | string | A corrected domain name when the supplied domain looks like a typo of a well-known provider (e.g. gmial.com → gmail.com). Null when no close match is found or the domain is already correct |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The email field is missing from the request body. |
| `bad_request` | 400 | The request body is missing, not valid JSON, or contains unknown fields. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/validation/email \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@gmial.com"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/email"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"email": "user@gmial.com"}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

result = data["data"]
print(result["valid"])       # False
print(result["suggestion"])  # "gmail.com"
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/validation/email', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'user@gmial.com' })
});

const { data } = await response.json();
console.log(data.valid);       // false
console.log(data.suggestion);  // "gmail.com"
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/email')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { email: 'user@gmial.com' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['valid']       # false
puts data['suggestion']  # gmail.com
```

## `POST /v1/validation/email/batch`

Validates up to 50 email addresses in a single request. Each email is processed independently and returns a full validation breakdown (syntax, MX record, disposable check, normalization, and typo suggestion). Invalid emails do not fail the request. Billing: 1 credit per email.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array<string> | Yes | Array of email addresses to validate. Min: 1, Max: 50. |

### Request

```json
{
  "emails": ["user@gmail.com", "user@gmial.com"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "email": "user@gmail.com",
        "valid": true,
        "syntax_valid": true,
        "mx_valid": true,
        "disposable": false,
        "normalized": "user@gmail.com",
        "domain": "gmail.com",
        "suggestion": null
      },
      {
        "email": "user@gmial.com",
        "valid": false,
        "syntax_valid": true,
        "mx_valid": false,
        "disposable": false,
        "normalized": "user@gmial.com",
        "domain": "gmial.com",
        "suggestion": "gmail.com"
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of validation results for each email, preserving input order |
| `results[].email` | string | Original email input (null if invalid syntax) |
| `results[].valid` | boolean | Overall validity (syntax + MX record) |
| `results[].syntax_valid` | boolean | Whether the email is syntactically valid (RFC 5322) |
| `results[].mx_valid` | boolean | Whether the domain has valid MX records |
| `results[].disposable` | boolean | Whether the email comes from a disposable domain |
| `results[].normalized` | string | Canonical normalized email (lowercase, alias handling, etc.) |
| `results[].domain` | string | Extracted domain from email address |
| `results[].suggestion` | string | Suggested correction for common domain typos |
| `total` | integer | Number of emails processed in the batch |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Valid JSON body that fails field validation (empty array or more than 50 emails). |
| `bad_request` | 400 | Invalid JSON, malformed request body, or unexpected field types. |
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/validation/email/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "user@gmial.com"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/email/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"emails": ["user@gmail.com", "user@gmial.com"]}

response = requests.post(url, headers=headers, json=payload)
data = response.json()["data"]

for r in data["results"]:
    print(r["email"], r["valid"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/validation/email/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: ['user@gmail.com', 'user@gmial.com']
  })
});

const { data } = await response.json();

data.results.forEach(r => {
  console.log(r.email, r.valid);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/email/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { emails: ['user@gmail.com', 'user@gmial.com'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']

data['results'].each do |r|
  puts "#{r['email']} #{r['valid']}"
end
```

---
# Phone Validation

Validate phone numbers globally. Detect carrier, country, number type, and VOIP or virtual risk using only phone metadata. No external lookups.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 966 ms |
| p95 | 1040 ms |
| p99 | 1070 ms |

## `GET /v1/validation/phone`

Validates a single phone number and returns its country, type, formatted representation, carrier, and VOIP/virtual risk flags.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `number` | string | Yes | The phone number to validate. Must include the country calling code (e.g. +12015551234). |

### Response Example

```json
{
  "data": {
    "number": "+447400123456",
    "valid": true,
    "country": "GB",
    "type": "mobile",
    "formatted": "+44 7400 123456",
    "carrier": {
      "name": "Three",
      "source": "metadata"
    },
    "risk": {
      "is_voip": false,
      "is_virtual": false
    }
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `number` | string | The original number as supplied in the request |
| `valid` | boolean | Whether the number is a valid, dialable phone number |
| `country` | string | ISO 3166-1 alpha-2 country code (omitted when valid is false) |
| `type` | string | Number type: mobile, landline, landline_or_mobile, toll_free, voip, premium_rate, shared_cost, personal_number, pager, uan, voicemail, or unknown (omitted when valid is false) |
| `formatted` | string | International format of the number, e.g. +44 7400 123456 (omitted when valid is false) |
| `carrier.name` | string | Carrier name from phone prefix metadata (omitted when carrier cannot be determined) |
| `carrier.source` | string | How the carrier was determined. Always "metadata" when present |
| `risk.is_voip` | boolean | true when the number type is voip |
| `risk.is_virtual` | boolean | true when the number is not tied to a physical SIM or fixed line: voip, personal_number, uan, pager, or voicemail |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The number query parameter is missing. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/validation/phone?number=%2B447400123456" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/phone"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"number": "+447400123456"}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

**Javascript**

```javascript
const number = encodeURIComponent('+447400123456');
const response = await fetch(
  `https://requiems.xyz/v1/validation/phone?number=${number}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.valid, data.carrier, data.risk);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/phone')
uri.query = URI.encode_www_form(number: '+447400123456')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['valid']
```

## `POST /v1/validation/phone/batch`

Validates up to 50 phone numbers in a single request. Results are returned in the same order as the input.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `numbers` | array<string> | Yes | Array of phone numbers to validate (min: 1, max: 50). Each must include the country calling code. |

### Request

```json
{
  "numbers": ["+447400123456", "+12015551234", "12345"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "number": "+447400123456",
        "valid": true,
        "country": "GB",
        "type": "mobile",
        "formatted": "+44 7400 123456",
        "carrier": { "name": "Three", "source": "metadata" },
        "risk": { "is_voip": false, "is_virtual": false }
      },
      {
        "number": "+12015551234",
        "valid": true,
        "country": "US",
        "type": "landline_or_mobile",
        "formatted": "+1 201-555-1234",
        "risk": { "is_voip": false, "is_virtual": false }
      },
      {
        "number": "12345",
        "valid": false
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Validation result for each number in the same order as the input. Each item has the same fields as the single validate endpoint. |
| `total` | integer | Number of results returned. Matches the length of the input array. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The numbers array is missing, empty, or contains more than 50 items. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/validation/phone/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+447400123456","+12015551234"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/phone/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"numbers": ["+447400123456", "+12015551234"]}

response = requests.post(url, headers=headers, json=payload)
for result in response.json()["data"]["results"]:
    print(result["number"], result["valid"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/validation/phone/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ numbers: ['+447400123456', '+12015551234'] })
  }
);

const { data } = await response.json();
data.results.forEach(r => console.log(r.number, r.valid));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/phone/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { numbers: ['+447400123456', '+12015551234'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |r|
  puts "#{r['number']}: #{r['valid']}"
end
```

---
# Profanity Filter

Detect and censor profanity in text. Returns a censored copy of the input and the list of flagged words found.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 822 ms |
| p95 | 935 ms |
| p99 | 1031 ms |

## `POST /v1/validation/profanity`

Checks text for profanity, returning a censored version and the list of flagged words.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | The text to check for profanity. |

### Request

```json
{
  "text": "Some text to check"
}
```

### Response Example

```json
{
  "data": {
    "has_profanity": false,
    "censored": "Some text to check",
    "flagged_words": []
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `has_profanity` | boolean | Whether any profanity was detected in the text |
| `censored` | string | The input text with profane words replaced by asterisks |
| `flagged_words` | array<string> | Deduplicated list of profane words found (lowercase) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The text field is missing or empty. |
| `bad_request` | 400 | The request body is missing or malformed. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/validation/profanity \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Some text to check"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/profanity"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"text": "Some text to check"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/validation/profanity', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Some text to check' })
});

const data = await response.json();
console.log(data.data.has_profanity);
console.log(data.data.censored);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/profanity')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { text: 'Some text to check' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['has_profanity']
puts data['data']['censored']
```

## `POST /v1/validation/profanity/batch`

Check up to 50 texts for profanity in a single request. Results are returned in input order.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `texts` | array<string> | Yes | List of texts to check (1–50 items, each non-empty). |

### Request

```json
{
  "texts": ["hello world", "some bad word here"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "text": "hello world",
        "result": { "has_profanity": false, "censored": "hello world", "flagged_words": [] }
      },
      {
        "text": "some bad word here",
        "result": { "has_profanity": true, "censored": "some *** word here", "flagged_words": ["bad"] }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].text` | string | The original text that was checked. |
| `results[].result.has_profanity` | boolean | Whether any profanity was detected. |
| `results[].result.censored` | string | Text with profane words replaced by asterisks. |
| `results[].result.flagged_words` | array<string> | Deduplicated list of detected profane words (lowercase). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The texts array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/validation/profanity/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["hello world", "some bad word here"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/validation/profanity/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"texts": ["hello world", "some bad word here"]}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    print(item["text"], item["result"]["has_profanity"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/validation/profanity/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ texts: ['hello world', 'some bad word here'] })
});

const { data } = await response.json();
data.results.forEach(item => {
  console.log(item.text, item.result.has_profanity);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/validation/profanity/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { texts: ['hello world', 'some bad word here'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each { |item| puts "#{item['text']}: #{item['result']['has_profanity']}" }
```

---
# IP Geolocation

Get geolocation data for any IP address including country, city, ISP, and VPN detection. Use this endpoint to enrich user data with location information for personalization, fraud detection, or content localization.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 995 ms |
| p95 | 1110 ms |
| p99 | 1243 ms |

## `GET /v1/networking/ip`

Get geolocation and network information for the requesting client's IP address. Useful when you want information about the user making the request without specifying an IP explicitly.

### Response Example

```json
{
  "data": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    "city": "Mountain View",
    "isp": "Google Public DNS",
    "is_vpn": false
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `ip` | string | The IP address that was looked up (the requesting client's IP) |
| `country` | string | Country name where the IP is located |
| `country_code` | string | Two-letter ISO country code (e.g., "US", "GB", "DE") |
| `city` | string | City name where the IP is located |
| `isp` | string | Internet Service Provider providing the IP |
| `is_vpn` | boolean | True when the IP belongs to a known VPN |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/ip" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.country, data.data.city);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/networking/ip')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

## `GET /v1/networking/ip/{ip}`

Get geolocation and network information for a specific IP address.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | Yes | The IP address to look up (supports IPv4 and IPv6) |

### Response Example

```json
{
  "data": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    "city": "Mountain View",
    "isp": "Google Public DNS",
    "is_vpn": false
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `ip` | string | The IP address that was looked up |
| `country` | string | Country name where the IP is located |
| `country_code` | string | Two-letter ISO country code (e.g., "US", "GB", "DE") |
| `city` | string | City name where the IP is located |
| `isp` | string | Internet Service Provider providing the IP |
| `is_vpn` | boolean | True when the IP belongs to a known VPN |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The IP address is invalid |
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/ip/8.8.8.8" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/8.8.8.8"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/8.8.8.8', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.country, data.data.city);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/networking/ip/8.8.8.8')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

## `POST /v1/networking/ip/info/batch`

Look up geolocation data for up to 50 IP addresses in a single request. Results are returned in input order. Per-item errors are reported inline.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ips` | array<string> | Yes | List of IP addresses to look up (1–50 items, each must be a valid IPv4 or IPv6 address). |

### Request

```json
{
  "ips": ["8.8.8.8", "1.1.1.1"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "ip": "8.8.8.8",
        "result": { "ip": "8.8.8.8", "country": "United States", "country_code": "US", "city": "Mountain View", "isp": "Google Public DNS", "is_vpn": false }
      },
      {
        "ip": "1.1.1.1",
        "result": { "ip": "1.1.1.1", "country": "Australia", "country_code": "AU", "city": "Sydney", "isp": "Cloudflare", "is_vpn": false }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].ip` | string | The IP address that was looked up. |
| `results[].result` | object | Geolocation data (omitted on error). Same fields as the single-item endpoint. |
| `results[].error` | string | Error message if the lookup failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The ips array is missing, empty, exceeds 50 items, or contains an invalid IP address. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/networking/ip/info/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/info/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"ips": ["8.8.8.8", "1.1.1.1"]}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["ip"], item["result"]["country"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/info/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ips: ['8.8.8.8', '1.1.1.1'] })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.ip, item.result.country);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/ip/info/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { ips: ['8.8.8.8', '1.1.1.1'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['ip']}: #{item['result']['country']}" if item['result']
end
```

---
# ASN Lookup

Look up Autonomous System Number (ASN), organization, ISP, domain, and network route information for any IP address. Use this endpoint to identify which organization or ISP owns an IP address and understand the network topology.

**Base URL:** `https://requiems.xyz`

## `GET /v1/networking/ip/asn`

Look up ASN, organization, ISP, and network details for the requesting client's IP address. Useful when you want information about the user making the request without specifying an IP explicitly.

### Response Example

```json
{
  "data": {
    "ip": "8.8.8.8",
    "asn": "AS15169",
    "org": "Google LLC",
    "isp": "Google Public DNS",
    "domain": "google.com",
    "route": "8.8.8.0/24",
    "type": "hosting"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `ip` | string | The IP address that was looked up (the requesting client's IP) |
| `asn` | string | Autonomous System Number in format "ASxxxx" (e.g., "AS15169") |
| `org` | string | Organization name owning the IP address range |
| `isp` | string | Internet Service Provider providing the IP |
| `domain` | string | Domain name associated with the IP or IP range |
| `route` | string | CIDR notation of the network route (e.g., "8.8.8.0/24") |
| `type` | string | Type of network (e.g., "hosting", "isp", "business", "cdn") |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/ip/asn" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/asn"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/asn', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.asn, data.data.org);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/networking/ip/asn')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

## `GET /v1/networking/ip/asn/{ip}`

Look up ASN, organization, ISP, and network details for a specific IP address.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | Yes | The IP address to look up (supports IPv4 and IPv6) |

### Response Example

```json
{
  "data": {
    "ip": "8.8.8.8",
    "asn": "AS15169",
    "org": "Google LLC",
    "isp": "Google Public DNS",
    "domain": "google.com",
    "route": "8.8.8.0/24",
    "type": "hosting"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `ip` | string | The IP address that was looked up |
| `asn` | string | Autonomous System Number in format "ASxxxx" (e.g., "AS15169") |
| `org` | string | Organization name owning the IP address range |
| `isp` | string | Internet Service Provider providing the IP |
| `domain` | string | Domain name associated with the IP or IP range |
| `route` | string | CIDR notation of the network route (e.g., "8.8.8.0/24") |
| `type` | string | Type of network (e.g., "hosting", "isp", "business", "cdn") |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The IP address is invalid |
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/ip/asn/8.8.8.8" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/asn/8.8.8.8"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/asn/8.8.8.8', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.asn, data.data.org);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/networking/ip/asn/8.8.8.8')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

## `POST /v1/networking/ip/asn/batch`

Look up ASN data for up to 50 IP addresses in a single request. Results are returned in input order. Private and reserved IPs return an empty result with no error.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ips` | array<string> | Yes | List of IP addresses to look up (1–50 items, each must be a valid IPv4 or IPv6 address). |

### Request

```json
{
  "ips": ["8.8.8.8", "1.1.1.1"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "ip": "8.8.8.8",
        "result": { "ip": "8.8.8.8", "asn": "AS15169", "org": "Google LLC", "isp": "Google Public DNS", "domain": "google.com", "route": "8.8.8.0/24", "type": "hosting" }
      },
      {
        "ip": "1.1.1.1",
        "result": { "ip": "1.1.1.1", "asn": "AS13335", "org": "Cloudflare, Inc.", "isp": "Cloudflare", "domain": "cloudflare.com", "route": "1.1.1.0/24", "type": "hosting" }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].ip` | string | The IP address that was looked up. |
| `results[].result` | object | ASN data (omitted on error). Same fields as the single-item endpoint. |
| `results[].error` | string | Error message if the lookup failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The ips array is missing, empty, exceeds 50 items, or contains an invalid IP address. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/networking/ip/asn/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/asn/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"ips": ["8.8.8.8", "1.1.1.1"]}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["ip"], item["result"]["asn"], item["result"]["org"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/asn/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ips: ['8.8.8.8', '1.1.1.1'] })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.ip, item.result.asn, item.result.org);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/ip/asn/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { ips: ['8.8.8.8', '1.1.1.1'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['ip']}: #{item['result']['asn']} #{item['result']['org']}" if item['result']
end
```

---
# VPN & Proxy Detection

Detect if an IP address belongs to a VPN, proxy, Tor exit node, or hosting provider. Returns threat scores and fraud indicators for fraud prevention, risk assessment, and bot detection.

**Base URL:** `https://requiems.xyz`

## `GET /v1/networking/ip/vpn/{ip}`

Analyze an IP address to determine if it's a VPN, proxy, Tor exit node, or hosting provider. Returns detailed threat indicators and scores.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | Yes | The IP address to check (supports IPv4 and IPv6) |

### Response Example

```json
{
  "data": {
    "ip": "8.8.8.8",
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_hosting": true,
    "score": 1,
    "threat": 1,
    "fraud_score": 0,
    "asn_org": "GOOGLE-ASN"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `ip` | string | The analyzed IP address |
| `is_vpn` | boolean | True when the IP belongs to a known VPN provider |
| `is_proxy` | boolean | True when the IP is a known public or web proxy |
| `is_tor` | boolean | True when the IP is a known Tor exit node |
| `is_hosting` | boolean | True when the IP belongs to a data-centre or hosting provider (DCH) |
| `score` | integer | Raw threat score (0-9+). Tor contributes 3, VPN or Proxy each contribute 2, Hosting contributes 1 |
| `threat` | integer | Threat level derived from score: 0 = None, 1 = Low, 2–3 = Medium, 4–5 = High, 6+ = Critical |
| `fraud_score` | integer | Fraud risk score from 0 (no risk) to 100 (high risk). Available when using IP2Proxy PX5 or higher |
| `asn_org` | string | Organization name owning the Autonomous System containing the IP (e.g. "DIGITALOCEAN-ASN") |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The IP address is missing or invalid |
| `internal_error` | 500 | Unexpected server error |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/ip/vpn/8.8.8.8" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/ip/vpn/8.8.8.8"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/ip/vpn/8.8.8.8', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.is_vpn, data.data.threat);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/networking/ip/vpn/8.8.8.8')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

---
# WHOIS Lookup

Get domain registration details including registrar, name servers, status, creation and expiry dates, and DNSSEC information.

**Base URL:** `https://requiems.xyz`

## `GET /v1/networking/whois/{domain}`

Returns WHOIS registration information for a domain name.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain` | string | Yes | The domain name to look up (e.g. example.com) |

### Response Example

```json
{
  "data": {
    "domain": "example.com",
    "registrar": "RESERVED-Internet Assigned Numbers Authority",
    "name_servers": [
      "A.IANA-SERVERS.NET",
      "B.IANA-SERVERS.NET"
    ],
    "status": [
      "clientDeleteProhibited",
      "clientTransferProhibited",
      "clientUpdateProhibited"
    ],
    "created_date": "1995-08-14T04:00:00Z",
    "updated_date": "2023-08-14T07:01:38Z",
    "expiry_date": "2024-08-13T04:00:00Z",
    "dnssec": true
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `domain` | string | The domain name that was looked up |
| `registrar` | string | The name of the registrar holding the domain registration |
| `name_servers` | array<string> | List of authoritative name servers for the domain |
| `status` | array<string> | EPP status codes for the domain (e.g. clientTransferProhibited) |
| `created_date` | string | Date the domain was first registered (ISO 8601) |
| `updated_date` | string | Date the domain record was last updated (ISO 8601) |
| `expiry_date` | string | Date the domain registration expires (ISO 8601) |
| `dnssec` | boolean | True when DNSSEC is enabled for the domain |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The domain name format is invalid. |
| `not_found` | 404 | No WHOIS record was found for the domain. |
| `internal_error` | 500 | Unexpected server error or upstream WHOIS query failure. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/whois/example.com" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/whois/example.com"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/whois/example.com', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.registrar, data.data.expiry_date);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/whois/example.com')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['registrar']
```

## `POST /v1/networking/whois/batch`

Returns WHOIS information for up to 50 domains in a single request. Results are returned in the same order as the input array. Domains without WHOIS data return found: false instead of failing the entire request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domains` | array<string> | Yes | Array of domain names. Min: 1, Max: 50. |

### Response Example

```json
{
  "data": {
    "results": [
      {
        "domain": "example.com",
        "found": true,
        "data": {
          "domain": "example.com",
          "registrar": "RESERVED-Internet Assigned Numbers Authority",
          "name_servers": [
            "A.IANA-SERVERS.NET",
            "B.IANA-SERVERS.NET"
          ],
          "status": [
            "clientDeleteProhibited"
          ],
          "created_date": "1995-08-14T04:00:00Z",
          "updated_date": "2023-08-14T07:01:38Z",
          "expiry_date": "2024-08-13T04:00:00Z",
          "dnssec": true
        }
      },
      {
        "domain": "doesnotexist.com",
        "found": false,
        "error": "domain not found"
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One entry per domain, in the same order as the input |
| `results[].domain` | string | Domain name requested in the batch |
| `results[].found` | boolean | False when WHOIS data could not be found |
| `results[].error` | string | Error message when found is false |
| `results[].data` | object | WHOIS information for the domain when found is true |
| `total` | integer | Total number of results returned |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Invalid request body. This includes empty arrays, more than 50 domains, invalid domain names, or malformed payloads. |
| `internal_error` | 500 | Unexpected server error during batch WHOIS lookup. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/networking/whois/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["example.com","google.com"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/whois/batch"

headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "domains": ["example.com", "google.com"]
}

response = requests.post(url, headers=headers, json=payload)

for item in response.json()["data"]["results"]:
    if item["found"]:
        print(item["data"]["registrar"])
    else:
        print(item["error"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/networking/whois/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domains: ['example.com', 'google.com']
    })
  }
);

const { data } = await response.json();

data.results.forEach(item => {
  if (item.found) {
    console.log(item.data.domain, item.data.registrar);
  } else {
    console.log(item.domain, item.error);
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/whois/batch')

request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  domains: ['example.com', 'google.com']
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

results = JSON.parse(response.body)['data']['results']

results.each do |item|
  if item['found']
    puts "#{item['domain']} -> #{item['data']['registrar']}"
  else
    puts "#{item['domain']} -> #{item['error']}"
  end
end
```

---
# Domain Info

Look up DNS records and check availability for any domain. Returns A, AAAA, MX, NS, TXT, and CNAME records alongside a registration availability flag derived from NS delegation.

**Base URL:** `https://requiems.xyz`

## `GET /v1/networking/domain/{domain}`

Returns DNS records and availability status for the given domain.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain` | string | Yes | The domain to look up (e.g. example.com) |

### Response Example

```json
{
  "data": {
    "domain": "example.com",
    "available": false,
    "dns": {
      "a": ["93.184.216.34"],
      "aaaa": ["2606:2800:220:1:248:1893:25c8:1946"],
      "mx": [],
      "ns": ["a.iana-servers.net.", "b.iana-servers.net."],
      "txt": ["v=spf1 -all"],
      "cname": ""
    }
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `domain` | string | The domain that was looked up |
| `available` | boolean | True when the domain appears to be unregistered (NS lookup returns NXDOMAIN). False when name servers are delegated. |
| `dns.a` | array<string> | IPv4 addresses (A records) |
| `dns.aaaa` | array<string> | IPv6 addresses (AAAA records) |
| `dns.mx` | array<object> | Mail exchange records, each with host and priority fields |
| `dns.ns` | array<string> | Authoritative name server hostnames |
| `dns.txt` | array<string> | TXT record values (SPF, DKIM, verification tokens, etc.) |
| `dns.cname` | string | CNAME alias target, if the domain is an alias. Empty string when no alias exists. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The domain parameter is not a valid hostname (e.g. missing TLD, invalid characters, or leading/trailing hyphens). |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/domain/example.com" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

domain = "example.com"
url = f"https://requiems.xyz/v1/networking/domain/{domain}"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data["data"]["available"], data["data"]["dns"]["a"])
```

**Javascript**

```javascript
const domain = 'example.com';
const response = await fetch(`https://requiems.xyz/v1/networking/domain/${domain}`, {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.available, data.data.dns.a);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

domain = 'example.com'
uri = URI("https://requiems.xyz/v1/networking/domain/#{domain}")
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['available']
puts data['data']['dns']['a'].inspect
```

---
# MX Lookup

Look up MX (Mail Exchange) records for any domain. Returns all mail server hostnames and their priorities, sorted from highest to lowest priority (ascending numeric value). Use this to verify email deliverability, discover mail server infrastructure, and diagnose email routing issues.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 944 ms |
| p95 | 1122 ms |
| p99 | 1229 ms |

## `GET /v1/networking/mx/{domain}`

Retrieve all MX records for a domain. Results are sorted by priority ascending (lowest numeric value has highest mail delivery priority per RFC 5321).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain` | string | Yes | The domain name to look up MX records for (e.g. gmail.com) |

### Response Example

```json
{
  "data": {
    "domain": "gmail.com",
    "records": [
      { "host": "gmail-smtp-in.l.google.com.", "priority": 5 },
      { "host": "alt1.gmail-smtp-in.l.google.com.", "priority": 10 },
      { "host": "alt2.gmail-smtp-in.l.google.com.", "priority": 20 },
      { "host": "alt3.gmail-smtp-in.l.google.com.", "priority": 30 },
      { "host": "alt4.gmail-smtp-in.l.google.com.", "priority": 40 }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `domain` | string | The domain that was queried |
| `records` | array<object> | List of MX records, sorted by priority ascending (lowest number = highest priority) |
| `records[].host` | string | Fully-qualified hostname of the mail server (typically ends with a trailing dot) |
| `records[].priority` | integer | MX priority value. Lower values have higher delivery priority per RFC 5321. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The domain parameter is not a valid domain name. |
| `not_found` | 404 | No MX records were found for the domain (domain may not accept email). |
| `internal_error` | 500 | DNS lookup failed due to an unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/mx/gmail.com" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/mx/gmail.com"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()["data"]
for record in data["records"]:
    print(record["priority"], record["host"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/mx/gmail.com', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const { data } = await response.json();
data.records.forEach(r => console.log(r.priority, r.host));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/mx/gmail.com')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['records'].each { |r| puts "#{r['priority']} #{r['host']}" }
```

## `POST /v1/networking/mx/batch`

Retrieve MX records for up to 50 domains in a single request. Results for each domain are sorted by priority ascending (lowest numeric value has the highest mail delivery priority per RFC 5321).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domains` | array<string> | Yes | Array of domains to lookup (min: 1, max: 50). |

### Request

```json
{
  "domains": ["outlook.com", "yahoo.com"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "domain": "outlook.com",
        "found": true,
        "data": {
          "domain": "outlook.com",
          "records": [
            {
              "host": "outlook-com.olc.protection.outlook.com.",
              "priority": 5
            }
          ]
          }
        },
        {
          "domain": "yahoo.com",
          "found": true,
          "data": {
            "domain": "yahoo.com",
            "records": [
              {
                "host": "mta5.am0.yahoodns.net.",
                "priority": 1
              },
              {
                "host": "mta7.am0.yahoodns.net.",
                "priority": 1
              },
              {
                "host": "mta6.am0.yahoodns.net.",
                "priority": 1
              }
            ]
          }
        }
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-05-13T21:34:51Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | MX lookup results for each input domain, in the same order as the input. |
| `results[].domain` | string | The domain name that was queried. |
| `results[].found` | boolean | Whether MX records were found for the domain. |
| `results[].error` | string | Error message if the lookup failed. Empty if found is true. |
| `results[].data` | object | MX lookup data. Present only when found is true. |
| `results[].data.domain` | string | The domain name associated with the MX records. |
| `results[].data.records` | array<object> | List of MX records sorted by priority ascending (lower value means higher priority). |
| `results[].data.records[].host` | string | Hostname of the mail server. |
| `results[].data.records[].priority` | number | Priority of the mail server. Lower value means higher priority. |
| `total` | number | Total number of results returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The domains array is missing, empty, or contains more than 50 items. |
| `internal_error` | 500 | DNS lookup failed due to an unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/networking/mx/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["outlook.com", "yahoo.com"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/mx/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"domains": ["outlook.com", "yahoo.com"]}

response = requests.post(url, headers=headers, json=payload)
for result in response.json()["data"]["results"]:
  print(result["domain"], result["found"])
  if result["found"]:
      for record in result["data"]["records"]:
        print(f"  {record['host']} (priority: {record['priority']})")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/mx/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domains: ['outlook.com', 'yahoo.com'] })
  }
);

const { data } = await response.json();
data.results.forEach(r => {
  console.log(r.domain, r.found);
  if (r.found) {
    r.data.records.forEach(record => {
      console.log(record.host, record.priority);
    });
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/mx/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { domains: ['outlook.com', 'yahoo.com'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |r|
  puts "#{r['domain']}: #{r['found']}"
  if r['found']
    r['data']['records'].each do |record|
      puts "  #{record['host']} (priority: #{record['priority']})"
    end
  end
end
```

---
# Disposable Email Checker

Detect disposable and temporary email addresses to prevent fraud and improve data quality. Our comprehensive blocklist is continuously updated to catch the latest disposable email providers.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 100 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 819 ms |
| p95 | 960 ms |
| p99 | 1116 ms |

## `POST /v1/networking/disposable/check`

Validate whether an email address uses a disposable domain

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | The email address to check |

### Request

```json
{
  "email": "user@tempmail.com"
}
```

### Response Example

```json
{
  "data": {
    "email": "user@tempmail.com",
    "is_disposable": true,
    "domain": "tempmail.com"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `email` | string | The email address that was checked |
| `is_disposable` | boolean | Whether the email uses a disposable domain |
| `domain` | string | The domain part of the email address |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The request body is missing or malformed |
| `400` |  | The email address format is invalid |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/networking/disposable/check \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@tempmail.com"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/disposable/check"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {"email": "user@tempmail.com"}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/disposable/check', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'user@tempmail.com' })
});

const data = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/networking/disposable/check')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { email: 'user@tempmail.com' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)
```

## `POST /v1/networking/disposable/batch`

Validate multiple email addresses in a single request (max 100 emails)

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array<string> | Yes | Array of email addresses to check (max 100) |

### Request

```json
{
  "emails": [
    "user1@gmail.com",
    "user2@tempmail.com",
    "user3@guerrillamail.com"
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "email": "user1@gmail.com",
        "is_disposable": false,
        "domain": "gmail.com"
      },
      {
        "email": "user2@tempmail.com",
        "is_disposable": true,
        "domain": "tempmail.com"
      },
      {
        "email": "user3@guerrillamail.com",
        "is_disposable": true,
        "domain": "guerrillamail.com"
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Array of check results for each email |
| `total` | integer | Total number of emails checked |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The request body is missing or malformed |
| `400` |  | The emails field is missing |
| `400` |  | Too many emails in the request |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/networking/disposable/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["user1@gmail.com", "user2@tempmail.com"]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/networking/disposable/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "emails": ["user1@gmail.com", "user2@tempmail.com"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/networking/disposable/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: ['user1@gmail.com', 'user2@tempmail.com']
  })
});

const data = await response.json();
console.log(data);
```

## `GET /v1/networking/disposable/domain/{domain}`

Check if a specific domain is in the disposable blocklist

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain` | string | Yes | The domain to check |

### Response Example

```json
{
  "data": {
    "domain": "tempmail.com",
    "is_disposable": true
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `domain` | string | The domain that was checked |
| `is_disposable` | boolean | Whether the domain is in the disposable blocklist |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The domain parameter is missing |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/networking/disposable/domain/tempmail.com \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

domain = "tempmail.com"
url = f"https://requiems.xyz/v1/networking/disposable/domain/{domain}"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const domain = 'tempmail.com';
const response = await fetch(
  `https://requiems.xyz/v1/networking/disposable/domain/${domain}`,
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data);
```

## `GET /v1/networking/disposable/stats`

Get statistics about the disposable email blocklist

### Response Example

```json
{
  "data": {
    "total_domains": 10500
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `total_domains` | integer | Total number of disposable domains in the blocklist |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/networking/disposable/stats \
  -H "requiems-api-key: YOUR_API_KEY"
```

## `GET /v1/networking/disposable/domains`

Get a paginated list of all disposable domains in the blocklist

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | No | Page number (default: 1) |
| `per_page` | integer | No | Items per page (default: 100, max: 1000) |

### Response Example

```json
{
  "data": {
    "domains": [
      "tempmail.com",
      "guerrillamail.com",
      "10minutemail.com"
    ],
    "total": 10500,
    "page": 1,
    "per_page": 100,
    "has_more": true
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `domains` | array<string> | Array of domain names |
| `total` | integer | Total number of domains in blocklist |
| `page` | integer | Current page number |
| `per_page` | integer | Number of items per page |
| `has_more` | boolean | Whether there are more pages available |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/networking/disposable/domains?page=1&per_page=100" \
  -H "requiems-api-key: YOUR_API_KEY"
```

---
# Timezone

Get timezone information for any location by geographic coordinates or city name. Returns the IANA timezone identifier, UTC offset, current time, and DST status.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/timezone`

Returns timezone information for the given coordinates or city name. Provide either `city` or both `lat` and `lon`.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | No | Latitude of the location (-90 to 90). Required when using coordinate-based lookup. |
| `lon` | number | No | Longitude of the location (-180 to 180). Required when using coordinate-based lookup. |
| `city` | string | No | City name for city-based lookup (e.g. 'Tokyo', 'London'). Required when not using coordinates. |

### Response Example

```json
{
  "timezone": "Europe/London",
  "offset": "+00:00",
  "current_time": "2024-12-15T14:30:00Z",
  "is_dst": false
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `timezone` | string | IANA timezone identifier (e.g. "Europe/London", "Asia/Tokyo") |
| `offset` | string | UTC offset in +HH:MM or -HH:MM format (e.g. '+05:30', '-05:00') |
| `current_time` | string | Current time in UTC, formatted as RFC 3339 (e.g. "2024-12-15T14:30:00Z") |
| `is_dst` | boolean | Whether the location is currently observing daylight saving time |

### Code Examples

**Curl**

```curl
# Lookup by coordinates
curl "https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1" \
  -H "requiems-api-key: YOUR_API_KEY"

# Lookup by city
curl "https://requiems.xyz/v1/places/timezone?city=Tokyo" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

# Lookup by coordinates
url = "https://requiems.xyz/v1/places/timezone"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params={"lat": 51.5, "lon": -0.1}, headers=headers)
print(response.json())

# Lookup by city
response = requests.get(url, params={"city": "Tokyo"}, headers=headers)
print(response.json())
```

**Javascript**

```javascript
// Lookup by coordinates
const response = await fetch(
  'https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.timezone);

// Lookup by city
const cityResponse = await fetch(
  'https://requiems.xyz/v1/places/timezone?city=Tokyo',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const cityData = await cityResponse.json();
console.log(cityData.data.timezone);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

# Lookup by coordinates
uri = URI('https://requiems.xyz/v1/places/timezone')
uri.query = URI.encode_www_form(lat: 51.5, lon: -0.1)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['timezone']
```

## `POST /v1/places/timezone/batch`

Look up timezone information for up to 50 locations in a single request. Each item can specify a timezone name, city, or lat/lon coordinates. Priority is timezone name > city > coordinates. Results are returned in input order.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of timezone lookup requests (1–50 items). |
| `items[].timezone` | string | No | IANA timezone name (e.g. 'America/New_York'). Highest priority. |
| `items[].city` | string | No | City name for city-based lookup. Used when timezone is not set. |
| `items[].lat` | number | No | Latitude (-90 to 90). Used when neither timezone nor city is set. |
| `items[].lon` | number | No | Longitude (-180 to 180). Used alongside lat for coordinate-based lookup. |

### Request

```json
{
  "items": [
    { "timezone": "America/New_York" },
    { "city": "Tokyo" },
    { "lat": 51.5, "lon": -0.1 }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "info": { "timezone": "America/New_York", "offset": "-05:00", "current_time": "2026-01-01T09:00:00Z", "is_dst": false } },
      { "info": { "timezone": "Asia/Tokyo",       "offset": "+09:00", "current_time": "2026-01-01T23:00:00Z", "is_dst": false } },
      { "info": { "timezone": "Europe/London",    "offset": "+00:00", "current_time": "2026-01-01T14:00:00Z", "is_dst": false } }
    ],
    "total": 3
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].info.timezone` | string | IANA timezone identifier. |
| `results[].info.offset` | string | UTC offset in +HH:MM or -HH:MM format. |
| `results[].info.current_time` | string | Current time in UTC (RFC 3339). |
| `results[].info.is_dst` | boolean | Whether daylight saving time is currently active. |
| `results[].error` | string | Error message if this item failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/places/timezone/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"timezone": "America/New_York"}, {"city": "Tokyo"}, {"lat": 51.5, "lon": -0.1}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/timezone/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"timezone": "America/New_York"},
        {"city": "Tokyo"},
        {"lat": 51.5, "lon": -0.1}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("info"):
        print(item["info"]["timezone"], item["info"]["offset"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/timezone/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { timezone: 'America/New_York' },
      { city: 'Tokyo' },
      { lat: 51.5, lon: -0.1 }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.info) console.log(item.info.timezone, item.info.offset);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/timezone/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { timezone: 'America/New_York' },
    { city: 'Tokyo' },
    { lat: 51.5, lon: -0.1 }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['info']['timezone']}: #{item['info']['offset']}" if item['info']
end
```

---
# World Time

Get the current time for any location in the world by specifying an IANA timezone identifier. Returns the timezone name, UTC offset, current time, and DST status.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/time/{timezone}`

Returns the current time for the given IANA timezone identifier. The timezone is supplied as a path parameter (e.g. `America/New_York`, `Europe/London`, `UTC`).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `timezone` | string | Yes | IANA timezone identifier (e.g. 'America/New_York', 'Europe/London', 'Asia/Kolkata') |

### Response Example

```json
{
  "data": {
    "timezone": "America/New_York",
    "offset": "-05:00",
    "current_time": "2024-12-15T14:30:00Z",
    "is_dst": false
  },
  "metadata": {
    "timestamp": "2024-12-15T14:30:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `timezone` | string | IANA timezone identifier (e.g. "America/New_York") |
| `offset` | string | UTC offset in +HH:MM or -HH:MM format (e.g. '-05:00', '+05:30') |
| `current_time` | string | Current time in UTC, formatted as RFC 3339 (e.g. "2024-12-15T14:30:00Z") |
| `is_dst` | boolean | Whether the timezone is currently observing daylight saving time |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/places/time/America/New_York" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/time/America/New_York"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/places/time/America/New_York',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.current_time);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/time/America/New_York')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['current_time']
```

---
# Working Days Calculator

Calculate the number of working days (business days) between two dates, with optional support for country-specific holidays. Useful for project planning, delivery estimates, and scheduling.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/working-days`

Calculate the number of working days between two dates, optionally accounting for country-specific holidays

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | Start date in YYYY-MM-DD format (ISO 8601) |
| `to` | string | Yes | End date in YYYY-MM-DD format (ISO 8601). Must be >= from date. |
| `country` | string | No | ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "FR"). When provided, country-specific holidays are excluded from working days count. |
| `subdivision` | string | No | ISO 3166-2 subdivision code for state/region within the country (e.g., "NY" for New York, "CA" for California). Only used when country is provided. |

### Response Example

```json
{
  "data": {
    "working_days": 4,
    "from": "2024-02-23",
    "to": "2024-02-28",
    "country": "US",
    "subdivision": "NY"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `working_days` | integer | Number of working days between the two dates (excluding weekends and optionally holidays) |
| `from` | string | Start date (echoed from request) |
| `to` | string | End date (echoed from request) |
| `country` | string | Country code (echoed from request, empty string if not provided) |
| `subdivision` | string | Subdivision code (echoed from request, empty string if not provided) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The from and to parameters are required, or to date is before from date, or invalid date format |

### Code Examples

**Curl**

```curl
# Without country (only excludes weekends)
curl "https://requiems.xyz/v1/places/working-days?from=2024-02-23&to=2024-02-28" \
  -H "requiems-api-key: YOUR_API_KEY"

# With country (excludes weekends and US federal holidays)
curl "https://requiems.xyz/v1/places/working-days?from=2024-02-23&to=2024-02-28&country=US" \
  -H "requiems-api-key: YOUR_API_KEY"

# With country and subdivision (excludes weekends and US + NY holidays)
curl "https://requiems.xyz/v1/places/working-days?from=2024-02-23&to=2024-02-28&country=US&subdivision=NY" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/working-days"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {
    "from": "2024-02-23",
    "to": "2024-02-28",
    "country": "US",
    "subdivision": "NY"
}

response = requests.get(url, headers=headers, params=params)
result = response.json()['data']
print(f"{result['working_days']} working days")
```

**Javascript**

```javascript
const params = new URLSearchParams({
  from: '2024-02-23',
  to: '2024-02-28',
  country: 'US',
  subdivision: 'NY'
});

const response = await fetch(
  `https://requiems.xyz/v1/places/working-days?${params}`,
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(`${data.working_days} working days`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/working-days')
uri.query = URI.encode_www_form(
  from: '2024-02-23',
  to: '2024-02-28',
  country: 'US',
  subdivision: 'NY'
)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "#{data['working_days']} working days"
```

---
# Holidays

Get a list of public holidays for any country and year. Useful for building calendar apps, scheduling, and compliance tools.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/holidays`

Returns a list of public holidays for the specified country and year

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `country` | string | Yes | ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE") |
| `year` | integer | Yes | Year for which to retrieve holidays (e.g., 2025) |

### Response Example

```json
{
  "data": {
    "country": "US",
    "year": 2025,
    "holidays": [
      {
        "date": "2025-01-01",
        "name": "New Year's Day"
      },
      {
        "date": "2025-07-04",
        "name": "Independence Day"
      }
    ],
    "total": 11
  },
  "metadata": {
    "timestamp": "2025-01-15T10:30:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `country` | string | ISO 3166-1 alpha-2 country code |
| `year` | integer | Year for which holidays are returned |
| `holidays` | array<object> | Array of holiday objects |
| `holidays[].date` | string | Holiday date in YYYY-MM-DD format |
| `holidays[].name` | string | Name of the holiday |
| `total` | integer | Total number of holidays for the country/year |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | Missing or invalid country code or year parameter |
| `not_found` | 404 | No holidays found for the specified country and year |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/places/holidays?country=US&year=2025" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/holidays"
params = {"country": "US", "year": 2025}
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/holidays?country=US&year=2025', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.holidays);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/holidays')
uri.query = URI.encode_www_form(country: 'US', year: 2025)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['holidays']
```

## `POST /v1/places/holidays/batch`

Returns holidays for up to 50 (country, year) pairs in a single request. Each pair is processed independently — if one combination has no data, it returns found:false without failing the entire batch.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `queries` | array<object> | Yes | Array of (country, year) pairs. Min: 1, Max: 50. |

### Response Example

```json
{
  "data": {
    "results": [
      {
        "country": "US",
        "year": 2025,
        "found": true,
        "holidays": [
          { "date": "2025-01-01", "name": "New Year's Day" },
          { "date": "2025-07-04", "name": "Independence Day" }
        ],
        "total": 11
      },
      {
        "country": "AR",
        "year": 2024,
        "found": true,
        "holidays": [
          { "date": "2024-01-01", "name": "Año Nuevo" }
        ],
        "total": 19
      },
      {
        "country": "AQ",
        "year": 2025,
        "found": false
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2025-01-15T10:30:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One result per query, in the same order as the request |
| `results[].country` | string | ISO 3166-1 alpha-2 country code |
| `results[].year` | integer | Year queried |
| `results[].found` | boolean | false when no holidays exist for that country/year combination |
| `results[].holidays` | array<object> | List of holidays. Omitted when found is false. |
| `results[].total` | integer | Number of holidays. Omitted when found is false. |
| `total` | integer | Total number of results (equals the number of queries sent) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | Malformed request body |
| `validation_failed` | 422 | queries is missing, empty, exceeds 50 items, or contains invalid country codes or years |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/places/holidays/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries":[{"country":"US","year":2025},{"country":"AR","year":2024}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/holidays/batch"
headers = {"requiems-api-key": "YOUR_API_KEY"}
body = {
    "queries": [
        {"country": "US", "year": 2025},
        {"country": "AR", "year": 2024},
    ]
}

response = requests.post(url, headers=headers, json=body)
for result in response.json()["data"]["results"]:
    if result["found"]:
        print(f"{result['country']} {result['year']}: {result['total']} holidays")
    else:
        print(f"{result['country']} {result['year']}: not found")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/holidays/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: [
      { country: 'US', year: 2025 },
      { country: 'AR', year: 2024 }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(r => {
  if (r.found) console.log(`${r.country} ${r.year}: ${r.total} holidays`);
  else console.log(`${r.country} ${r.year}: not found`);
});
```

---
# Geocoding

Convert human-readable addresses into geographic coordinates (geocoding) and convert coordinates back into addresses (reverse geocoding). Powered by OpenStreetMap via the Nominatim API.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/geocode`

Converts a free-text address into latitude and longitude coordinates.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `address` | string | Yes | The address to geocode (street, city, country, or any combination) |

### Response Example

```json
{
  "data": {
    "address": "White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States",
    "city": "Washington",
    "country": "US",
    "lat": 38.8976763,
    "lon": -77.0365298
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `address` | string | Full display name of the matched location |
| `city` | string | City or town of the matched location |
| `country` | string | ISO 3166-1 alpha-2 country code (uppercase) |
| `lat` | number | Latitude of the matched location |
| `lon` | number | Longitude of the matched location |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No results found for the given address. |
| `upstream_error` | 503 | The geocoding service is temporarily unavailable. |
| `bad_request` | 400 | The address parameter is missing. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/places/geocode?address=1600+Pennsylvania+Ave+NW" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/geocode"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params={"address": "1600 Pennsylvania Ave NW"}, headers=headers)
data = response.json()
print(data["data"]["lat"], data["data"]["lon"])
```

**Javascript**

```javascript
const params = new URLSearchParams({ address: '1600 Pennsylvania Ave NW' });
const response = await fetch(
  `https://requiems.xyz/v1/places/geocode?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.lat, data.data.lon);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/geocode')
uri.query = URI.encode_www_form(address: '1600 Pennsylvania Ave NW')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts "#{data['data']['lat']}, #{data['data']['lon']}"
```

## `GET /v1/places/reverse-geocode`

Converts geographic coordinates into a human-readable address.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | Yes | Latitude of the location (-90 to 90) |
| `lon` | number | Yes | Longitude of the location (-180 to 180) |

### Response Example

```json
{
  "data": {
    "lat": 38.8977,
    "lon": -77.0365,
    "address": "White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States",
    "city": "Washington",
    "country": "US"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `lat` | number | Latitude as provided in the request |
| `lon` | number | Longitude as provided in the request |
| `address` | string | Full display name of the location at the given coordinates |
| `city` | string | City or town at the given coordinates |
| `country` | string | ISO 3166-1 alpha-2 country code (uppercase) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No address found for the given coordinates. |
| `upstream_error` | 503 | The geocoding service is temporarily unavailable. |
| `bad_request` | 400 | lat or lon is missing or out of range (lat: -90..90, lon: -180..180). |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/places/reverse-geocode?lat=38.8977&lon=-77.0365" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/reverse-geocode"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params={"lat": 38.8977, "lon": -77.0365}, headers=headers)
data = response.json()
print(data["data"]["address"])
```

**Javascript**

```javascript
const params = new URLSearchParams({ lat: 38.8977, lon: -77.0365 });
const response = await fetch(
  `https://requiems.xyz/v1/places/reverse-geocode?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.address);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/reverse-geocode')
uri.query = URI.encode_www_form(lat: 38.8977, lon: -77.0365)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['address']
```

## `POST /v1/places/geocode/batch`

Convert up to 20 addresses to coordinates in a single request. Processed concurrently; results are returned in input order. Per-item errors are reported inline. Cache hits avoid outbound network calls.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `addresses` | array<string> | Yes | List of addresses to geocode (1–20 items, each non-empty). Max 20 due to Nominatim usage policy. |

### Request

```json
{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington DC",
    "Eiffel Tower, Paris"
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "address": "1600 Pennsylvania Ave NW, Washington DC",
        "result": { "address": "White House, 1600, Pennsylvania Avenue Northwest...", "city": "Washington", "country": "US", "lat": 38.8977, "lon": -77.0365 }
      },
      {
        "address": "Eiffel Tower, Paris",
        "result": { "address": "Tour Eiffel, 5, Avenue Anatole France, Paris...", "city": "Paris", "country": "FR", "lat": 48.8584, "lon": 2.2945 }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].address` | string | The original address as provided in the request. |
| `results[].result` | object | Geocoding result (omitted on error). Same fields as the single-item endpoint. |
| `results[].error` | string | Error message if geocoding failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The addresses array is missing, empty, or exceeds 20 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/places/geocode/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["1600 Pennsylvania Ave NW, Washington DC", "Eiffel Tower, Paris"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/geocode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"addresses": ["1600 Pennsylvania Ave NW, Washington DC", "Eiffel Tower, Paris"]}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["result"]["lat"], item["result"]["lon"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/geocode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: ['1600 Pennsylvania Ave NW, Washington DC', 'Eiffel Tower, Paris']
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.result.lat, item.result.lon);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/geocode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  addresses: ['1600 Pennsylvania Ave NW, Washington DC', 'Eiffel Tower, Paris']
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['result']['lat']}, #{item['result']['lon']}" if item['result']
end
```

## `POST /v1/places/reverse-geocode/batch`

Convert up to 20 coordinate pairs to addresses in a single request. Processed concurrently; results are returned in input order. Per-item errors are reported inline.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of coordinate pairs to reverse-geocode (1–20 items). Max 20 due to Nominatim usage policy. |
| `items[].lat` | number | Yes | Latitude (-90 to 90). |
| `items[].lon` | number | Yes | Longitude (-180 to 180). |

### Request

```json
{
  "items": [
    { "lat": 38.8977, "lon": -77.0365 },
    { "lat": 48.8584, "lon": 2.2945 }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "lat": 38.8977, "lon": -77.0365,
        "result": { "lat": 38.8977, "lon": -77.0365, "address": "White House, 1600, Pennsylvania Avenue Northwest...", "city": "Washington", "country": "US" }
      },
      {
        "lat": 48.8584, "lon": 2.2945,
        "result": { "lat": 48.8584, "lon": 2.2945, "address": "Tour Eiffel, 5, Avenue Anatole France, Paris...", "city": "Paris", "country": "FR" }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].lat` | number | Latitude as provided in the request. |
| `results[].lon` | number | Longitude as provided in the request. |
| `results[].result` | object | Reverse geocoding result (omitted on error). Same fields as the single-item endpoint. |
| `results[].error` | string | Error message if reverse geocoding failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 20 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/places/reverse-geocode/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"lat": 38.8977, "lon": -77.0365}, {"lat": 48.8584, "lon": 2.2945}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/reverse-geocode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"lat": 38.8977, "lon": -77.0365},
        {"lat": 48.8584, "lon": 2.2945}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["result"]["address"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/reverse-geocode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { lat: 38.8977, lon: -77.0365 },
      { lat: 48.8584, lon: 2.2945 }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.result.address);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/reverse-geocode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { lat: 38.8977, lon: -77.0365 },
    { lat: 48.8584, lon: 2.2945 }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts item['result']['address'] if item['result']
end
```

---
# Postal Code

Look up city, state, and geographic coordinates for any postal code worldwide. Covers 100+ countries using the GeoNames postal code dataset.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/postal/{code}`

Returns city, state, country, and coordinates for the given postal code.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | The postal code to look up (e.g. 10001 for New York, SW1A 1AA for London) |
| `country` | string | No | ISO 3166-1 alpha-2 country code (default: US) |

### Response Example

```json
{
  "data": {
    "postal_code": "10001",
    "city": "New York City",
    "state": "New York",
    "country": "US",
    "lat": 40.7484,
    "lon": -73.9967
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `postal_code` | string | The postal code as stored in the dataset |
| `city` | string | Primary city or place name for the postal code |
| `state` | string | State, province, or administrative region name |
| `country` | string | ISO 3166-1 alpha-2 country code (uppercase) |
| `lat` | number | Latitude of the postal code centroid |
| `lon` | number | Longitude of the postal code centroid |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | The postal code was not found for the given country. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
# US zip code (default country)
curl "https://requiems.xyz/v1/places/postal/10001" \
  -H "requiems-api-key: YOUR_API_KEY"

# UK postcode
curl "https://requiems.xyz/v1/places/postal/SW1A1AA?country=GB" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/postal/10001"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params={"country": "US"}, headers=headers)
data = response.json()
print(data["data"]["city"])   # New York City
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/places/postal/10001?country=US',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.city);  // New York City
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/postal/10001')
uri.query = URI.encode_www_form(country: 'US')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['city']
```

## `POST /v1/places/postal/batch`

Look up city, state, and coordinates for up to 50 postal codes in a single request. Results are returned in input order.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of postal code lookups (1–50 items). |
| `items[].code` | string | Yes | The postal code to look up. |
| `items[].country` | string | No | ISO 3166-1 alpha-2 country code (default: US). |

### Request

```json
{
  "items": [
    { "code": "10001", "country": "US" },
    { "code": "SW1A1AA", "country": "GB" }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "code": "10001", "country": "US", "found": true,
        "result": { "postal_code": "10001", "city": "New York City", "state": "New York", "country": "US", "lat": 40.7484, "lon": -73.9967 }
      },
      {
        "code": "SW1A1AA", "country": "GB", "found": true,
        "result": { "postal_code": "SW1A 1AA", "city": "London", "state": "England", "country": "GB", "lat": 51.5010, "lon": -0.1247 }
      }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].code` | string | The postal code as provided in the request. |
| `results[].country` | string | The country code used for the lookup (defaulted to US when omitted). |
| `results[].found` | boolean | Whether the postal code was found in the dataset. |
| `results[].result` | object | Postal code details (omitted when found is false). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/places/postal/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"code": "10001", "country": "US"}, {"code": "SW1A1AA", "country": "GB"}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/postal/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"code": "10001", "country": "US"},
        {"code": "SW1A1AA", "country": "GB"}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item["found"]:
        print(item["code"], item["result"]["city"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/places/postal/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { code: '10001', country: 'US' },
      { code: 'SW1A1AA', country: 'GB' }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.found) console.log(item.code, item.result.city);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/postal/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { code: '10001', country: 'US' },
    { code: 'SW1A1AA', country: 'GB' }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['code']}: #{item['result']['city']}" if item['found']
end
```

---
# Cities

Look up metadata for cities worldwide including population, IANA timezone, and geographic coordinates. Covers ~22,000 cities with a population above 15,000 from the GeoNames dataset.

**Base URL:** `https://requiems.xyz`

## `GET /v1/places/cities/{city}`

Returns metadata for a city by name. Lookup is case-insensitive.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `city` | string | Yes | City name to look up (e.g. london, tokyo, new york city) |

### Response Example

```json
{
  "data": {
    "name": "London",
    "country": "GB",
    "population": 7556900,
    "timezone": "Europe/London",
    "lat": 51.5085,
    "lon": -0.1257
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Official city name as listed in the GeoNames dataset |
| `country` | string | ISO 3166-1 alpha-2 country code (uppercase) |
| `population` | integer | City population from the GeoNames dataset |
| `timezone` | string | IANA timezone identifier for the city (e.g. "America/New_York") |
| `lat` | number | Latitude of the city centre |
| `lon` | number | Longitude of the city centre |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No city with that name was found in the dataset. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/places/cities/london" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/places/cities/london"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data["data"]["timezone"])  # Europe/London
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/places/cities/london',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.timezone);  // Europe/London
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/cities/london')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['timezone']
```

---
# Spell Check

Check spelling and get correction suggestions. Returns a corrected version of the input text and a list of individual corrections with their positions.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 807 ms |
| p95 | 1147 ms |
| p99 | 1280 ms |

## `POST /v1/text/spellcheck`

Checks the input text for spelling mistakes and returns a corrected version along with per-word corrections.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | The text to spell-check. |

### Request

```json
{
  "text": "Ths is a smiple tset"
}
```

### Response Example

```json
{
  "data": {
    "corrected": "This is a simple test",
    "corrections": [
      {
        "original": "Ths",
        "suggested": "This",
        "suggestions": ["Th's", "Th", "This"],
        "position": 0
      },
      {
        "original": "smiple",
        "suggested": "simple",
        "suggestions": ["simple", "smile", "Siple"],
        "position": 9
      },
      {
        "original": "tset",
        "suggested": "test",
        "suggestions": ["set", "test", "stet"],
        "position": 16
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `corrected` | string | The full input text with all misspelled words replaced by the top-ranked suggestion |
| `corrections` | array<object> | List of individual corrections. Each item contains: original (the misspelled word), suggested (the top-ranked replacement applied to corrected), suggestions (up to 3 ranked alternatives returned by LanguageTool, from most to least likely), and position (0-based Unicode character offset in the original text) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The text field is missing or empty. |
| `bad_request` | 400 | The request body is missing or malformed. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/spellcheck \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ths is a smiple tset"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/spellcheck"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"text": "Ths is a smiple tset"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/spellcheck', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Ths is a smiple tset' })
});

const data = await response.json();
console.log(data.data.corrected);
console.log(data.data.corrections);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/spellcheck')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { text: 'Ths is a smiple tset' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['corrected']
data['data']['corrections'].each { |c| puts "#{c['original']} -> #{c['suggested']}" }
```

## `POST /v1/text/spellcheck/batch`

Checks multiple texts for spelling mistakes in a single request. Returns a corrected version and per-word corrections for each input text. Results are returned in the same order as the input array.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `texts` | array<string> | Yes | The list of texts to spell-check. Between 1 and 50 items. |

### Request

```json
{
  "texts": ["Ths is a tset", "Smiple example"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "corrected": "This is a test",
        "corrections": [
          {
            "original": "Ths",
            "suggested": "This",
            "suggestions": ["Th's", "Th", "This"],
            "position": 0
          },
          {
            "original": "tset",
            "suggested": "test",
            "suggestions": ["set", "test", "stet"],
            "position": 9
          }
        ]
      },
      {
        "corrected": "Simple example",
        "corrections": [
          {
            "original": "Smiple",
            "suggested": "Simple",
            "suggestions": ["Simple", "Smile", "Siple"],
            "position": 0
          }
        ]
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One entry per input text, in the same order as the input array. Each item contains corrected (the fixed text) and corrections (list of individual corrections with original, suggested, suggestions, and position). |
| `total` | integer | Number of texts processed. Equals the length of the input array. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The texts field is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/spellcheck/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Ths is a tset", "Smiple example"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/spellcheck/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"texts": ["Ths is a tset", "Smiple example"]}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
for item in data["data"]["results"]:
    print(item["corrected"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/spellcheck/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ texts: ['Ths is a tset', 'Smiple example'] })
});

const data = await response.json();
data.data.results.forEach(item => console.log(item.corrected));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/spellcheck/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { texts: ['Ths is a tset', 'Smiple example'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
data['data']['results'].each { |item| puts item['corrected'] }
```

---
# Thesaurus

Find synonyms and antonyms for any word. Perfect for vocabulary building, writing assistance, and educational applications.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 829 ms |
| p95 | 1104 ms |
| p99 | 1228 ms |

## `GET /v1/text/thesaurus/{word}`

Returns synonyms and antonyms for the given word.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `word` | string | Yes | The word to look up in the thesaurus |

### Response Example

```json
{
  "data": {
    "word": "happy",
    "synonyms": ["joyful", "cheerful", "content", "pleased", "delighted", "glad", "elated", "blissful"],
    "antonyms": ["sad", "unhappy", "miserable", "sorrowful", "dejected", "gloomy", "melancholy"]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `word` | string | The normalized (lowercased) word that was looked up |
| `synonyms` | array<string> | List of words with similar meaning |
| `antonyms` | array<string> | List of words with opposite meaning |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | The word was not found in the thesaurus dataset. |
| `bad_request` | 400 | The word path parameter is missing. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/text/thesaurus/happy \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/thesaurus/happy"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()['data']
print(f"Synonyms: {data['synonyms']}")
print(f"Antonyms: {data['antonyms']}")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/thesaurus/happy', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log('Synonyms:', data.synonyms);
console.log('Antonyms:', data.antonyms);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/thesaurus/happy')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "Synonyms: #{data['synonyms'].join(', ')}"
puts "Antonyms: #{data['antonyms'].join(', ')}"
```

---
# Dictionary

Get word definitions, IPA phonetics, usage examples, and synonyms in a single request. Perfect for vocabulary tools, writing assistants, and educational applications.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 950 ms |
| p95 | 1139 ms |
| p99 | 1222 ms |

## `GET /v1/text/dictionary/{word}`

Returns the definition, phonetics, examples, and synonyms for the given word.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `word` | string | Yes | The word to look up in the dictionary |

### Response Example

```json
{
  "data": {
    "word": "ephemeral",
    "phonetic": "/ɪˈfɛm(ə)rəl/",
    "definitions": [
      {
        "part_of_speech": "adjective",
        "definition": "lasting for a very short time",
        "example": "ephemeral pleasures"
      }
    ],
    "synonyms": ["transient", "fleeting", "momentary", "brief", "short-lived"]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `word` | string | The normalized (lowercased) word that was looked up |
| `phonetic` | string | IPA phonetic transcription of the word (may be omitted if unavailable) |
| `definitions` | array<object> | One or more definitions for the word, each with part_of_speech, definition, and an optional example |
| `definitions[].part_of_speech` | string | Grammatical category (e.g. noun, verb, adjective) |
| `definitions[].definition` | string | Plain-text definition of the word |
| `definitions[].example` | string | Example sentence using the word (may be omitted) |
| `synonyms` | array<string> | List of words with similar meaning |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | The word was not found in the dictionary dataset. |
| `bad_request` | 400 | The word path parameter is missing. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/text/dictionary/ephemeral \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/dictionary/ephemeral"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()['data']
print(f"{data['word']} {data['phonetic']}")
for d in data['definitions']:
    print(f"  [{d['part_of_speech']}] {d['definition']}")
    if d.get('example'):
        print(f"  Example: {d['example']}")
print(f"Synonyms: {', '.join(data['synonyms'])}")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/dictionary/ephemeral', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(`${data.word} ${data.phonetic}`);
data.definitions.forEach(d => {
  console.log(`  [${d.part_of_speech}] ${d.definition}`);
  if (d.example) console.log(`  Example: ${d.example}`);
});
console.log('Synonyms:', data.synonyms.join(', '));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/dictionary/ephemeral')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "#{data['word']} #{data['phonetic']}"
data['definitions'].each do |d|
  puts "  [#{d['part_of_speech']}] #{d['definition']}"
  puts "  Example: #{d['example']}" if d['example']
end
puts "Synonyms: #{data['synonyms'].join(', ')}"
```

## `POST /v1/text/words/batch`

Resolve multiple words in a single request. Returns dictionary entries when found, or error information when a word is not in the dataset.


### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<string> | Yes | List of words to look up in batch (max 50 items) |

### Request

```json
{
  "items": ["ephemeral", "serendipity", "melancholy"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "word": "serendipity",
        "found": true,
        "entry": {
          "word": "serendipity",
          "phonetic": "/ˌserənˈdipədē/",
          "definitions": [
            {
              "part_of_speech": "noun",
              "definition": "the occurrence of events by chance in a happy way"
            }
          ],
          "synonyms": ["fluke", "chance", "fortuity"]
        }
      },
      {
        "word": "fakeword",
        "found": false,
        "error": "word not found: fakeword"
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of batch lookup results |
| `total` | integer | Total number of items processed |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  | Invalid or empty items array |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/text/words/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":["example"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/words/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = { "items": ["example"] }
response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/words/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 'items': ["example"] })
});
const { data } = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/words/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { "items" => ["example"] }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']
```

---
# Sentiment Analysis

Analyze the sentiment of any text and get back a positive, negative, or neutral classification with a confidence score and full breakdown.

**Base URL:** `https://requiems.xyz`

## `POST /v1/text/sentiment`

Analyzes the sentiment of the provided text and returns a classification, confidence score, and a full breakdown across all three sentiment classes.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | The text to analyze. |

### Request

```json
{
  "text": "I absolutely love this product, it exceeded my expectations!"
}
```

### Response Example

```json
{
  "data": {
    "sentiment": "positive",
    "score": 0.97,
    "breakdown": {
      "positive": 0.97,
      "negative": 0.01,
      "neutral": 0.02
    }
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `sentiment` | string | The dominant sentiment class: positive, negative, or neutral |
| `score` | number | Confidence score for the dominant sentiment, between 0.0 and 1.0 |
| `breakdown.positive` | number | Proportional score for positive sentiment (sums to 1.0 with other classes) |
| `breakdown.negative` | number | Proportional score for negative sentiment (sums to 1.0 with other classes) |
| `breakdown.neutral` | number | Proportional score for neutral sentiment (sums to 1.0 with other classes) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  |  |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/sentiment \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "I absolutely love this product!"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/sentiment"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"text": "I absolutely love this product!"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()['data']
print(f"{data['sentiment']} ({data['score']:.2f})")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/text/sentiment',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: 'I absolutely love this product!' })
  }
);
const { data } = await response.json();
console.log(`${data.sentiment} (${data.score.toFixed(2)})`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/sentiment')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { text: 'I absolutely love this product!' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "#{data['sentiment']} (#{data['score'].round(2)})"
```

## `POST /v1/text/sentiment/batch`

Analyzes the sentiment of up to 50 texts in a single request. Results are returned in the same order as the input. Each text counts as one unit of usage.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `texts` | array<string> | Yes | The list of texts to analyze. Between 1 and 50 items. |

### Request

```json
{
  "texts": [
    "I love this product! It's absolutely amazing.",
    "This is terrible. I hate it.",
    "The document is on the table."
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "sentiment": "positive",
        "score": 0.91,
        "breakdown": { "positive": 0.91, "negative": 0.02, "neutral": 0.07 }
      },
      {
        "sentiment": "negative",
        "score": 0.88,
        "breakdown": { "positive": 0.03, "negative": 0.88, "neutral": 0.09 }
      },
      {
        "sentiment": "neutral",
        "score": 1.0,
        "breakdown": { "positive": 0.0, "negative": 0.0, "neutral": 1.0 }
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Sentiment results for each input text, in the same order as the input. |
| `results[].sentiment` | string | The dominant sentiment class: positive, negative, or neutral |
| `results[].score` | number | Confidence score for the dominant sentiment, between 0.0 and 1.0 |
| `results[].breakdown.positive` | number | Proportional score for positive sentiment (sums to 1.0 with other classes) |
| `results[].breakdown.negative` | number | Proportional score for negative sentiment (sums to 1.0 with other classes) |
| `results[].breakdown.neutral` | number | Proportional score for neutral sentiment (sums to 1.0 with other classes) |
| `total` | number | Total number of results returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  |  |
| `422` |  |  |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/sentiment/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["I love this!", "This is terrible.", "The table is there."]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/sentiment/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "texts": [
        "I love this!",
        "This is terrible.",
        "The table is there."
    ]
}

response = requests.post(url, json=payload, headers=headers)
for item in response.json()['data']['results']:
    print(f"{item['sentiment']} ({item['score']:.2f})")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/text/sentiment/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      texts: ['I love this!', 'This is terrible.', 'The table is there.']
    })
  }
);
const { data } = await response.json();
data.results.forEach(r => console.log(`${r.sentiment} (${r.score.toFixed(2)})`));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/sentiment/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  texts: ['I love this!', 'This is terrible.', 'The table is there.']
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |r|
  puts "#{r['sentiment']} (#{r['score'].round(2)})"
end
```

---
# Language Detection

Detect the language of any text and receive the language name, ISO 639-1 code, and a confidence score.

**Base URL:** `https://requiems.xyz`

## `POST /v1/text/detect-language`

Identifies the language of the provided text and returns the language name, ISO 639-1 code, and confidence score.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | The text whose language should be detected. |

### Request

```json
{
  "text": "Bonjour, comment ça va?"
}
```

### Response Example

```json
{
  "data": {
    "language": "French",
    "code": "fr",
    "confidence": 0.98
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `language` | string | Full name of the detected language (e.g. French, English, Spanish) |
| `code` | string | ISO 639-1 two-letter language code (e.g. fr, en, es). Empty string when detection is unreliable. |
| `confidence` | number | Confidence score between 0.0 and 1.0. 0.0 is returned when the language cannot be reliably detected. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The text field is missing or empty. |
| `bad_request` | 400 | The request body is missing or malformed. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/detect-language \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour, comment ça va?"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/detect-language"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"text": "Bonjour, comment ça va?"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/detect-language', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Bonjour, comment ça va?' })
});

const data = await response.json();
console.log(data.data.language);
console.log(data.data.code);
console.log(data.data.confidence);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/detect-language')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { text: 'Bonjour, comment ça va?' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['language']
puts data['data']['code']
puts data['data']['confidence']
```

---
# Text Similarity

Compare two pieces of text and get a similarity score between 0 and 1 using cosine similarity on word-frequency vectors.

**Base URL:** `https://requiems.xyz`

## `POST /v1/text/similarity`

Compares two texts and returns a cosine similarity score.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text1` | string | Yes | The first text to compare. |
| `text2` | string | Yes | The second text to compare. |

### Request

```json
{
  "text1": "The cat sat on the mat",
  "text2": "A cat was sitting on a mat"
}
```

### Response Example

```json
{
  "data": {
    "similarity": 0.4364,
    "method": "cosine"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `similarity` | number | Cosine similarity score between the two texts, in the range [0, 1]. |
| `method` | string | The algorithm used. Currently always 'cosine'. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | One or both text fields are missing or empty. |
| `bad_request` | 400 | The request body is missing or malformed. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/similarity \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text1": "The cat sat on the mat", "text2": "A cat was sitting on a mat"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/similarity"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "text1": "The cat sat on the mat",
    "text2": "A cat was sitting on a mat"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data["data"]["similarity"])
print(data["data"]["method"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/similarity', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text1: 'The cat sat on the mat',
    text2: 'A cat was sitting on a mat'
  })
});

const data = await response.json();
console.log(data.data.similarity);
console.log(data.data.method);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/similarity')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  text1: 'The cat sat on the mat',
  text2: 'A cat was sitting on a mat'
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['similarity']
puts data['data']['method']
```

---
# Markdown to HTML

Convert Markdown text to HTML in a single API call. Optionally sanitize the output to strip unsafe tags and prevent XSS.

**Base URL:** `https://requiems.xyz`

## `POST /v1/technology/markdown`

Converts a Markdown string to HTML. Pass sanitize true to strip potentially unsafe tags like script and iframe from the output.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `markdown` | string | Yes | The Markdown text to convert. |
| `sanitize` | boolean | No | When true, sanitizes the HTML output to remove unsafe tags and attributes. |

### Request

```json
{
  "markdown": "# Hello\n\nThis is **bold** and _italic_ text.",
  "sanitize": true
}
```

### Response Example

```json
{
  "data": {
    "html": "<h1>Hello</h1>\n<p>This is <strong>bold</strong> and <em>italic</em> text.</p>\n"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `html` | string | The rendered HTML output |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  |  |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/markdown \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nThis is **bold** text.", "sanitize": true}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/markdown"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "markdown": "# Hello\n\nThis is **bold** text.",
    "sanitize": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.json()['data']['html'])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/markdown',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      markdown: '# Hello\n\nThis is **bold** text.',
      sanitize: true
    })
  }
);
const { data } = await response.json();
console.log(data.html);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/markdown')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  markdown: "# Hello\n\nThis is **bold** text.",
  sanitize: true
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)['data']['html']
```

## `POST /v1/technology/markdown/batch`

Converts multiple Markdown strings into HTML in a single request. Results are returned in the same order as the input array. Supports optional sanitization to remove unsafe HTML tags such as script and iframe.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `markdowns` | array<string> | Yes | Array of Markdown strings. Min: 1, Max: 50. |
| `sanitize` | boolean | No | When true, sanitizes HTML output to remove unsafe tags and attributes. |

### Request

```json
{
  "markdowns": [
    "# Hello",
    "**bold**",
    "- item one"
  ],
  "sanitize": true
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "html": "<h1>Hello</h1>" },
      { "html": "<p><strong>bold</strong></p>" },
      { "html": "<ul>\n<li>item one</li>\n</ul>" }
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One HTML result per Markdown input, preserving input order |
| `results[].html` | string | Rendered HTML output for each Markdown string |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Body is invalid: empty array, more than 50 items, or invalid Markdown entry. |
| `bad_request` | 400 | Missing or malformed request body. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/markdown/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdowns": ["# Hello", "**bold**", "- item"],
    "sanitize": true
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/markdown/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "markdowns": ["# Hello", "**bold**", "- item"],
    "sanitize": True
}

response = requests.post(url, json=payload, headers=headers)
results = response.json()["data"]["results"]

for r in results:
    print(r["html"])
```

**Javascript**

```javascript
const response = await fetch(
  "https://requiems.xyz/v1/technology/markdown/batch",
  {
    method: "POST",
    headers: {
      "requiems-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      markdowns: ["# Hello", "**bold**", "- item"],
      sanitize: true
    })
  }
);

const { data } = await response.json();
console.log(data.results);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/markdown/batch')

request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  markdowns: ["# Hello", "**bold**", "- item"],
  sanitize: true
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

results = JSON.parse(response.body)['data']['results']
puts results
```

---
# Lorem Ipsum Generator

Generate classic Lorem Ipsum placeholder text for design mockups, prototypes, and testing. Customize the number of paragraphs and sentences per paragraph.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 100 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 928 ms |
| p95 | 1230 ms |
| p99 | 1398 ms |

## `GET /v1/text/lorem`

Generate Lorem Ipsum placeholder text with customizable length and format

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `paragraphs` | integer | No | Number of paragraphs to generate (1-20) |
| `sentences` | integer | No | Number of sentences per paragraph (1-20) |

### Response Example

```json
{
  "data": {
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.",
    "paragraphs": 1,
    "word_count": 45
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Generated Lorem Ipsum text |
| `paragraphs` | integer | Number of paragraphs generated |
| `word_count` | integer | Total number of words in generated text |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The paragraphs parameter is out of valid range |
| `400` |  | The sentences parameter is out of valid range |

### Code Examples

**Curl**

```curl
# Generate 3 paragraphs with 5 sentences each
curl "https://requiems.xyz/v1/text/lorem?paragraphs=3&sentences=5" \
  -H "requiems-api-key: YOUR_API_KEY"

# Generate 1 paragraph with 10 sentences
curl "https://requiems.xyz/v1/text/lorem?sentences=10" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/lorem"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"paragraphs": 3, "sentences": 5}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

**Javascript**

```javascript
const params = new URLSearchParams({ paragraphs: 3, sentences: 5 });
const response = await fetch(
  `https://requiems.xyz/v1/text/lorem?${params}`,
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data.data.text);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/lorem')
uri.query = URI.encode_www_form(paragraphs: 3, sentences: 5)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['text']
```

## `POST /v1/text/lorem/batch`

Generate multiple Lorem Ipsum placeholder texts in a single request. Processes items in bulk and returns partial successes.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | Array of text generation requests. Minimum 1 item, maximum 50 items. |
| `items[].paragraphs` | integer | No | Number of paragraphs to generate (1-20) |
| `items[].sentences` | integer | No | Number of sentences per paragraph (1-20) |

### Response Example

```json
{
  "data": [
    {
      "data": {
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...",
        "paragraphs": 2,
        "word_count": 90
      }
    },
    {
      "error": "sentences must be between 1 and 20"
    }
  ],
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z",
    "usage_count": 2
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `data[].data` | object | Contains the generated text if the specific item was successful |
| `data[].error` | string | Error message if the specific item failed to generate |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  | The request body is malformed, missing the items array, or exceeds the maximum batch size of 50 items. |

### Code Examples

**Curl**

```curl
# Generate a batch of 2 different text configurations
curl -X POST "https://requiems.xyz/v1/text/lorem/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"paragraphs": 2, "sentences": 3}, {"paragraphs": 1}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/lorem/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"paragraphs": 2, "sentences": 3},
        {"paragraphs": 1}
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/lorem/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { paragraphs: 2, sentences: 3 },
      { paragraphs: 1 }
    ]
  })
});

const data = await response.json();
console.log(data);
```

---
# Random Word

Get random words with definitions and parts of speech. Perfect for vocabulary builders, educational apps, word games, or content inspiration.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 951 ms |
| p95 | 1352 ms |
| p99 | 1426 ms |

## `GET /v1/text/words/random`

Returns a random word with its definition and part of speech

### Response Example

```json
{
  "data": {
    "id": 123,
    "word": "ephemeral",
    "definition": "lasting for a very short time",
    "part_of_speech": "adjective"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique identifier for the word |
| `word` | string | The random word |
| `definition` | string | Dictionary definition of the word |
| `part_of_speech` | string | Grammatical classification (e.g., noun, verb, adjective, adverb) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `503` |  | No words available in the database |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/text/words/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/words/random"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
word_data = response.json()['data']
print(f"{word_data['word']} ({word_data['part_of_speech']}): {word_data['definition']}")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/words/random', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(`${data.word} (${data.part_of_speech}): ${data.definition}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/words/random')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
 puts "#{data['word']} (#{data['part_of_speech']}): #{data['definition']}"
```

---
# Email Normalizer

Normalize email addresses to their canonical form. Strips plus tags, removes provider-specific dots, lowercases, trims whitespace, and resolves alias domains (e.g. googlemail.com → gmail.com). Returns the normalized address, its parts, and a list of every change applied.

**Base URL:** `https://requiems.xyz`

## `POST /v1/text/normalize`

Normalizes a single email address and returns the canonical form together with a breakdown of all transformations applied.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | The email address to normalize. Must be a syntactically valid address. |

### Request

```json
{
  "email": "Te.st.User+spam@Googlemail.com"
}
```

### Response Example

```json
{
  "data": {
    "original": "Te.st.User+spam@Googlemail.com",
    "normalized": "testuser@gmail.com",
    "local": "testuser",
    "domain": "gmail.com",
    "changes": [
      "lowercased",
      "removed_dots",
      "removed_plus_tag",
      "canonicalised_domain"
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `original` | string | The email address exactly as supplied in the request body |
| `normalized` | string | The canonical form of the address after all transformations |
| `local` | string | The local part (before @) of the normalized address |
| `domain` | string | The domain part (after @) of the normalized address |
| `changes` | array<string> | Ordered list of transformations applied. Possible values: lowercased, trimmed_whitespace, removed_dots, removed_plus_tag, canonicalised_domain. Empty array when no changes were needed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The email field is missing or not a valid email address format. |
| `bad_request` | 400 | The request body is missing, not valid JSON, or contains unknown fields. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/normalize \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "Te.st.User+spam@Googlemail.com"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/normalize"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"email": "Te.st.User+spam@Googlemail.com"}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data["data"]["normalized"])  # testuser@gmail.com
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/normalize', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'Te.st.User+spam@Googlemail.com' })
});

const { data } = await response.json();
console.log(data.normalized); // testuser@gmail.com
console.log(data.changes);    // ["lowercased", "removed_dots", ...]
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/text/normalize')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { email: 'Te.st.User+spam@Googlemail.com' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['normalized'] # testuser@gmail.com
```

## `POST /v1/text/normalize/batch`

Normalizes up to 100 email addresses in one request. Results are in the same order as the input. Each item includes valid (boolean); when false, only original and message are set. Usage is billed per email processed (see gateway usage headers).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array<string> | Yes | Array of addresses to normalize (min 1, max 100; each entry non-empty) |

### Request

```json
{
  "emails": [
    "user@example.com",
    "not-an-email",
    "te.st@gmail.com"
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "original": "user@example.com",
        "normalized": "user@example.com",
        "local": "user",
        "domain": "example.com",
        "changes": [],
        "valid": true
      },
      {
        "original": "not-an-email",
        "valid": false,
        "message": "invalid email address"
      },
      {
        "original": "te.st@gmail.com",
        "normalized": "test@gmail.com",
        "local": "test",
        "domain": "gmail.com",
        "changes": ["lowercased", "removed_dots"],
        "valid": true
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | One normalization result per input email, in order |
| `total` | integer | Number of emails in the batch (same as results length) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Missing emails, empty array, too many items, or empty string in the array |
| `bad_request` | 400 | Invalid JSON or unknown fields in the body |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/text/normalize/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["user@example.com","te.st@gmail.com"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/text/normalize/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {"emails": ["user@example.com", "te.st@gmail.com"]}
response = requests.post(url, headers=headers, json=data)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/text/normalize/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ emails: ['user@example.com', 'te.st@gmail.com'] })
});
console.log(await response.json());
```

---
# QR Code Generator

Generate QR codes from any text or URL. Returns a raw PNG image or base64-encoded JSON, with configurable size and error-correction level.

**Base URL:** `https://requiems.xyz`

## `GET /v1/technology/qr`

Returns a raw PNG image of the QR code. Ideal for direct embedding or file download.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `data` | string | Yes | The text or URL to encode in the QR code |
| `size` | integer | No | Image size in pixels (default: 256, min: 50, max: 1000) |
| `recovery` | string | No | Error-correction level: low (7%), medium (15%), high (25%), highest (30%). Higher levels are more robust to physical damage but produce larger images. Default: medium |

### Response Example

```json
<binary PNG image data>
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `(binary)` | bytes | Raw PNG image bytes. Content-Type is image/png. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or invalid parameters (e.g. data not provided, size out of range, unknown recovery level) |
| `500` |  | Failed to generate QR code |

### Code Examples

**Curl**

```curl
# Save a 200px PNG with high error-correction
curl "https://requiems.xyz/v1/technology/qr?data=https://example.com&size=200&recovery=high" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output qrcode.png

# Default size (256px), medium error-correction
curl "https://requiems.xyz/v1/technology/qr?data=https://example.com" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output qrcode.png
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/qr"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"data": "https://example.com", "size": 200, "recovery": "high"}

response = requests.get(url, headers=headers, params=params)
with open("qrcode.png", "wb") as f:
    f.write(response.content)
```

**Javascript**

```javascript
const params = new URLSearchParams({
  data: 'https://example.com',
  size: 200,
  recovery: 'high'
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/qr?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const blob = await response.blob();
const imgUrl = URL.createObjectURL(blob);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/technology/qr')
uri.query = URI.encode_www_form(data: 'https://example.com', size: 200, recovery: 'high')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
File.write('qrcode.png', response.body, mode: 'wb')
```

## `GET /v1/technology/qr/base64`

Returns a JSON envelope containing the QR code as a base64-encoded PNG string, along with its dimensions.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `data` | string | Yes | The text or URL to encode in the QR code |
| `size` | integer | No | Image size in pixels (default: 256, min: 50, max: 1000) |
| `recovery` | string | No | Error-correction level: low (7%), medium (15%), high (25%), highest (30%). Default: medium |

### Response Example

```json
{
  "data": {
    "image": "<base64-encoded PNG data>",
    "width": 256,
    "height": 256
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `image` | string | Base64-encoded PNG image data |
| `width` | integer | Width of the generated image in pixels |
| `height` | integer | Height of the generated image in pixels |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or invalid parameters (e.g. data not provided, size out of range, unknown recovery level) |
| `500` |  | Failed to generate QR code |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/technology/qr/base64?data=https://example.com&size=200&recovery=highest" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/qr/base64"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"data": "https://example.com", "size": 200, "recovery": "highest"}

response = requests.get(url, headers=headers, params=params)
result = response.json()["data"]
print(f"Image (base64): {result['image'][:40]}...")
```

**Javascript**

```javascript
const params = new URLSearchParams({
  data: 'https://example.com',
  size: 200,
  recovery: 'highest'
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/qr/base64?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
// Use as an <img> src
document.getElementById('qr').src = `data:image/png;base64,${data.image}`;
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/qr/base64')
uri.query = URI.encode_www_form(data: 'https://example.com', size: 200, recovery: 'highest')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)['data']
puts data['image'][0..39] + '...'
```

## `POST /v1/technology/qr/base64/batch`

Generate up to 50 base64-encoded QR codes in a single request. Results are returned in input order. The PNG endpoint has no batch variant — use this endpoint for batch generation.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of QR generation requests (1–50 items). |
| `items[].data` | string | Yes | The text or URL to encode. |
| `items[].size` | integer | No | Image size in pixels (50–1000). Defaults to 256. |
| `items[].recovery` | string | No | Error-correction level: low, medium, high, highest. Defaults to medium. |

### Request

```json
{
  "items": [
    { "data": "https://example.com", "size": 256, "recovery": "medium" },
    { "data": "Hello, World!" }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "data": "https://example.com", "image": "<base64>", "width": 256, "height": 256 },
      { "data": "Hello, World!",        "image": "<base64>", "width": 256, "height": 256 }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].data` | string | The input text or URL that was encoded. |
| `results[].image` | string | Base64-encoded PNG image data (omitted on error). |
| `results[].width` | integer | Width of the generated image in pixels (omitted on error). |
| `results[].height` | integer | Height of the generated image in pixels (omitted on error). |
| `results[].error` | string | Error message if generation failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/qr/base64/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"data": "https://example.com"}, {"data": "Hello, World!"}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/qr/base64/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"data": "https://example.com", "size": 256},
        {"data": "Hello, World!"}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("image"):
        print(f"{item['data']}: {item['image'][:20]}...")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/qr/base64/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { data: 'https://example.com', size: 256 },
      { data: 'Hello, World!' }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.image) {
    document.getElementById('qr').src = `data:image/png;base64,${item.image}`;
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/qr/base64/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { data: 'https://example.com', size: 256 },
    { data: 'Hello, World!' }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts item['image'][0..19] + '...' if item['image']
end
```

---
# Barcode Generator

Generate barcodes in multiple industry-standard formats. Returns a raw PNG image or base64-encoded JSON, supporting Code 128, Code 93, Code 39, EAN-8, and EAN-13.

**Base URL:** `https://requiems.xyz`

## `GET /v1/technology/barcode`

Returns a raw PNG image of the barcode. Ideal for direct embedding or file download.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `data` | string | Yes | The text or numeric string to encode in the barcode |
| `type` | string | Yes | Barcode format: code128, code93, code39, ean8, ean13 |

### Response Example

```json
<binary PNG image data>
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `(binary)` | bytes | Raw PNG image bytes. Content-Type is image/png. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or invalid parameters (e.g. data not provided, unsupported type) |
| `422` |  | Data is invalid for the chosen barcode type (e.g. wrong digit count for EAN-8/EAN-13, non-numeric EAN data) |

### Code Examples

**Curl**

```curl
# Save a Code 128 barcode as PNG
curl "https://requiems.xyz/v1/technology/barcode?data=123456789&type=code128" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output barcode.png

# Save an EAN-13 barcode (12 digits, checksum auto-calculated)
curl "https://requiems.xyz/v1/technology/barcode?data=123456789012&type=ean13" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output barcode.png
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/barcode"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"data": "123456789", "type": "code128"}

response = requests.get(url, headers=headers, params=params)
with open("barcode.png", "wb") as f:
    f.write(response.content)
```

**Javascript**

```javascript
const params = new URLSearchParams({
  data: '123456789',
  type: 'code128'
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/barcode?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const blob = await response.blob();
const imgUrl = URL.createObjectURL(blob);
```

**Ruby**

```ruby
require 'net/http'

uri = URI('https://requiems.xyz/v1/technology/barcode')
uri.query = URI.encode_www_form(data: '123456789', type: 'code128')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
File.write('barcode.png', response.body, mode: 'wb')
```

## `GET /v1/technology/barcode/base64`

Returns a JSON envelope containing the barcode as a base64-encoded PNG string, along with its type and dimensions.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `data` | string | Yes | The text or numeric string to encode in the barcode |
| `type` | string | Yes | Barcode format: code128, code93, code39, ean8, ean13 |

### Response Example

```json
{
  "data": {
    "image": "<base64-encoded PNG data>",
    "type": "code128",
    "width": 300,
    "height": 100
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `image` | string | Base64-encoded PNG image data |
| `type` | string | The barcode format that was used |
| `width` | integer | Width of the generated image in pixels |
| `height` | integer | Height of the generated image in pixels |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or invalid parameters (e.g. data not provided, unsupported type) |
| `422` |  | Data is invalid for the chosen barcode type (e.g. wrong digit count for EAN-8/EAN-13, non-numeric EAN data) |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/technology/barcode/base64?data=123456789&type=code128" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/barcode/base64"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"data": "123456789", "type": "code128"}

response = requests.get(url, headers=headers, params=params)
result = response.json()["data"]
print(f"Image (base64): {result['image'][:40]}...")
```

**Javascript**

```javascript
const params = new URLSearchParams({
  data: '123456789',
  type: 'code128'
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/barcode/base64?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
// Use as an <img> src
document.getElementById('barcode').src = `data:image/png;base64,${data.image}`;
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/barcode/base64')
uri.query = URI.encode_www_form(data: '123456789', type: 'code128')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)['data']
puts data['image'][0..39] + '...'
```

## `POST /v1/technology/barcode/batch`

Generate up to 20 barcodes in a single request. Each barcode is processed independently and results are returned in the same order as the input. Invalid items do not fail the entire request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | Array of barcode generation requests. Min: 1, Max: 20. |

### Request

```json
{
  "items": [
    {
      "data": "123456789",
      "type": "code128"
    },
    {
      "data": "1234567",
      "type": "ean8"
    }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAA...",
        "type": "code128",
        "width": 300,
        "height": 100,
        "success": true,
        "error": ""
      },
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAA...",
        "type": "ean8",
        "width": 300,
        "height": 100,
        "success": true,
        "error": ""
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of barcode generation results preserving input order |
| `results[].image` | string | Base64-encoded PNG image |
| `results[].type` | string | Barcode format used |
| `results[].width` | integer | Image width in pixels |
| `results[].height` | integer | Image height in pixels |
| `results[].success` | boolean | Whether barcode generation succeeded |
| `results[].error` | string | Error message when generation fails |
| `total` | integer | Number of items processed |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | Valid request body that fails validation (empty items array, more than 20 items, missing data field, or unsupported barcode type). |
| `bad_request` | 400 | Invalid JSON or malformed request body. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/barcode/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "data": "123456789",
        "type": "code128"
      },
      {
        "data": "HELLO",
        "type": "code93"
      }
    ]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/barcode/batch"

response = requests.post(
    url,
    headers={
        "requiems-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "items": [
            {
                "data": "123456789",
                "type": "code128"
            },
            {
                "data": "HELLO",
                "type": "code93"
            }
        ]
    }
)

print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/barcode/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      items: [
        {
          data: '123456789',
          type: 'code128'
        },
        {
          data: 'HELLO',
          type: 'code93'
        }
      ]
    })
  }
);

const { data } = await response.json();
console.log(data.results);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/barcode/batch')

request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  items: [
    {
      data: '123456789',
      type: 'code128'
    },
    {
      data: 'HELLO',
      type: 'code93'
    }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

---
# Password Generator

Generate cryptographically secure random passwords with customizable complexity. Perfect for user registration, password reset flows, or security tools.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 100 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 939 ms |
| p95 | 1125 ms |
| p99 | 1223 ms |

## `GET /v1/technology/password`

Generate a cryptographically secure random password with customizable character sets and length

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `length` | integer | No | Password length (8-128 characters) |
| `uppercase` | boolean | No | Include uppercase letters (A-Z) |
| `numbers` | boolean | No | Include numbers (0-9) |
| `symbols` | boolean | No | Include special characters (!@#$%^&*()-_=+[]{}|;:,.<>?) |

### Response Example

```json
{
  "data": {
    "password": "aB3#cDeFgHiJkLmN",
    "length": 16,
    "strength": "strong"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `password` | string | The generated password |
| `length` | integer | Length of the generated password |
| `strength` | string | Password strength assessment (weak, medium, or strong) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | The length parameter is out of valid range (8-128) |
| `500` |  | Failed to generate password (rare cryptographic failure) |

### Code Examples

**Curl**

```curl
# Generate 16-character password with all character types
curl "https://requiems.xyz/v1/technology/password?length=16&uppercase=true&numbers=true&symbols=true" \
  -H "requiems-api-key: YOUR_API_KEY"

# Generate simple 12-character password (lowercase only)
curl "https://requiems.xyz/v1/technology/password?length=12" \
  -H "requiems-api-key: YOUR_API_KEY"

# Generate 20-character alphanumeric password
curl "https://requiems.xyz/v1/technology/password?length=20&uppercase=true&numbers=true" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/password"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {
    "length": 16,
    "uppercase": True,
    "numbers": True,
    "symbols": True
}

response = requests.get(url, headers=headers, params=params)
result = response.json()['data']
print(f"Password: {result['password']}")
print(f"Strength: {result['strength']}")
```

**Javascript**

```javascript
const params = new URLSearchParams({
  length: 16,
  uppercase: true,
  numbers: true,
  symbols: true
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/password?${params}`,
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(`Password: ${data.password}`);
console.log(`Strength: ${data.strength}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/password')
uri.query = URI.encode_www_form(
  length: 16,
  uppercase: true,
  numbers: true,
  symbols: true
)

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "Password: #{data['password']}"
puts "Strength: #{data['strength']}"
```

## `POST /v1/technology/password/batch`

Generate up to 50 passwords in a single request. Each item can have its own length and character set options. Results are returned in input order.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of password generation requests (1–50 items). |
| `items[].length` | integer | No | Password length (8–128). Defaults to 16 when omitted. |
| `items[].uppercase` | boolean | No | Include uppercase letters (A–Z). Defaults to false. |
| `items[].numbers` | boolean | No | Include numbers (0–9). Defaults to false. |
| `items[].symbols` | boolean | No | Include special characters. Defaults to false. |

### Request

```json
{
  "items": [
    { "length": 16, "uppercase": true, "numbers": true, "symbols": true },
    { "length": 12 }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "result": { "password": "aB3#cDeFgHiJkLmN", "length": 16, "strength": "strong" } },
      { "result": { "password": "abcdefghijkl",     "length": 12, "strength": "weak"   } }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].result.password` | string | The generated password (omitted on error). |
| `results[].result.length` | integer | Length of the generated password. |
| `results[].result.strength` | string | Strength assessment (weak, medium, or strong). |
| `results[].error` | string | Error message if generation failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/password/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"length": 16, "uppercase": true, "numbers": true, "symbols": true}, {"length": 12}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/password/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"length": 16, "uppercase": True, "numbers": True, "symbols": True},
        {"length": 12}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["result"]["password"], item["result"]["strength"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/password/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { length: 16, uppercase: true, numbers: true, symbols: true },
      { length: 12 }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.result.password, item.result.strength);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/password/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { length: 16, uppercase: true, numbers: true, symbols: true },
    { length: 12 }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts item['result']['password'] if item['result']
end
```

---
# User Agent Parser

Parse user agent strings to extract browser name, version, operating system, device type, and bot detection.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 928 ms |
| p95 | 1051 ms |
| p99 | 1122 ms |

## `GET /v1/technology/useragent`

Parses a user agent string and returns structured information about the browser, OS, device, and bot status.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ua` | string | Yes | The user agent string to parse. |

### Response Example

```json
{
  "data": {
    "browser": "Chrome",
    "browser_version": "120.0",
    "os": "Windows",
    "os_version": "10/11",
    "device": "desktop",
    "is_bot": false
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `browser` | string | Detected browser name (e.g. Chrome, Firefox, Safari, Edge, Opera, Internet Explorer, Other) |
| `browser_version` | string | Detected browser version (major.minor) |
| `os` | string | Detected operating system (e.g. Windows, macOS, Linux, Android, iOS, ChromeOS, Other) |
| `os_version` | string | Detected OS version (format varies by platform) |
| `device` | string | Device type — one of desktop, mobile, tablet, bot, or unknown |
| `is_bot` | boolean | True when the user agent matches a known bot or crawler pattern |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The ua query parameter is missing. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/technology/useragent?ua=Mozilla%2F5.0+%28Windows+NT+10.0%29+Chrome%2F120.0.0.0" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests
from urllib.parse import quote

ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"
url = f"https://requiems.xyz/v1/technology/useragent?ua={quote(ua)}"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0";
const url = `https://requiems.xyz/v1/technology/useragent?ua=${encodeURIComponent(ua)}`;

const response = await fetch(url, {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});

const data = await response.json();
console.log(data.data.browser);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"
uri = URI("https://requiems.xyz/v1/technology/useragent?ua=#{URI.encode_www_form_component(ua)}")
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['browser']
```

## `POST /v1/technology/useragent/batch`

Parses up to 50 user agents in a single request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `user_agents` | array<string> | Yes | Array of user agents to parse (min: 1, max: 50). |

### Request

```json
{
   "user_agents": [
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
     "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15"
   ]
 }
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
        "data": {
          "browser": "Chrome",
          "browser_version": "124.0",
          "os": "Windows",
          "os_version": "10/11",
          "device": "desktop",
          "is_bot": false
        }
      },
      {
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15",
        "data": {
          "browser": "Safari",
          "browser_version": "",
          "os": "iOS",
          "os_version": "17.0",
          "device": "mobile",
          "is_bot": false
        }
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-05-19T05:33:14Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of parsed user agents results returned in the same order as the input user agents. |
| `results[].user_agent` | string | The original user agent string from the input. |
| `results[].data` | object | Parsed user agent details. |
| `results[].data.browser` | string | Detected browser name (e.g. Chrome, Firefox, Safari, Edge, Opera, Internet Explorer, Other). Empty if not detected. |
| `results[].data.browser_version` | string | Detected browser version (major.minor). Empty if not detected. |
| `results[].data.os` | string | Detected operating system (e.g. Windows, macOS, Linux, Android, iOS, ChromeOS, Other). Empty if not detected. |
| `results[].data.os_version` | string | Detected OS version (format varies by platform). Empty if not detected. |
| `results[].data.device` | string | Device type — one of desktop, mobile, tablet, bot, or unknown |
| `results[].data.is_bot` | boolean | True when the user agent matches a known bot or crawler pattern |
| `total` | integer | Total number of parsed user agent results returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The user_agents array is missing, empty, or contains more than 50 items. |
| `bad_request` | 400 | Invalid JSON, malformed request body, or unexpected field types. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/technology/useragent/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_agents": [
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
      "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15"
    ]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/useragent/batch"

headers = {
  "requiems-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

payload = {
  "user_agents": [
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15"
  ]
}

response = requests.post(url, headers=headers, json=payload)

for item in response.json()["data"]["results"]:
  print(item["user_agent"])
  print("Browser:", item["data"]["browser"], item["data"]["browser_version"])
  print("OS:", item["data"]["os"], item["data"]["os_version"])
  print("Device:", item["data"]["device"])
  print("Is Bot:", item["data"]["is_bot"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/useragent/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_agents: [
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
        'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15'
      ]
    })
  }
);

const { data } = await response.json();

data.results.forEach(item => {
  console.log(item.user_agent);
  console.log('Browser:', item.data.browser, item.data.browser_version);
  console.log('OS:', item.data.os, item.data.os_version);
  console.log('Device:', item.data.device);
  console.log('Is Bot:', item.data.is_bot);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/useragent/batch')

request = Net::HTTP::Post.new(uri)

request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  user_agents: [
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15'
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |item|
  puts item['user_agent']
  puts "Browser: #{item['data']['browser']} #{item['data']['browser_version']}"
  puts "OS: #{item['data']['os']} #{item['data']['os_version']}"
  puts "Device: #{item['data']['device']}"
  puts "Is Bot: #{item['data']['is_bot']}"
end
```

---
# Counter

Atomic, namespace-isolated hit counter. Perfect for tracking page views, downloads, or any event that needs counting.

**Base URL:** `https://requiems.xyz`

## `POST /v1/technology/counter/{namespace}`

Atomically increment a counter in the specified namespace and return the new value

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `namespace` | string | Yes | Counter namespace (1-64 chars: alphanumeric, hyphen, underscore) |

### Response Example

```json
{
  "data": {
    "namespace": "page-views",
    "value": 42
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `namespace` | string | The counter namespace |
| `value` | integer | The new counter value after increment |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Invalid namespace: must be 1–64 chars, alphanumeric, hyphen or underscore only |
| `500` |  | Internal server error |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/counter/page-views \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/counter/page-views"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.post(url, headers=headers)
data = response.json()['data']
print(f"Counter '{data['namespace']}' is now at {data['value']}")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/counter/page-views',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(`Counter '${data.namespace}' is now at ${data.value}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/counter/page-views')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "Counter '#{data['namespace']}' is now at #{data['value']}"
```

## `GET /v1/technology/counter/{namespace}`

Get the current value of a counter without incrementing it

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `namespace` | string | Yes | Counter namespace (1-64 chars: alphanumeric, hyphen, underscore) |

### Response Example

```json
{
  "data": {
    "namespace": "page-views",
    "value": 42
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `namespace` | string | The counter namespace |
| `value` | integer | The current counter value (returns 0 if counter doesn't exist) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Invalid namespace: must be 1–64 chars, alphanumeric, hyphen or underscore only |
| `500` |  | Internal server error |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/technology/counter/page-views \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/counter/page-views"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()['data']
print(f"Counter '{data['namespace']}' is at {data['value']}")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/counter/page-views',
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(`Counter '${data.namespace}' is at ${data.value}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/counter/page-views')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "Counter '#{data['namespace']}' is at #{data['value']}"
```

---
# Random User

Generate random fake user profiles for testing and prototyping. Each call returns a unique name, email address, phone number, mailing address, and avatar URL.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 817 ms |
| p95 | 1161 ms |
| p99 | 1241 ms |

## `GET /v1/technology/random-user`

Returns a randomly generated fake user profile.

### Response Example

```json
{
  "data": {
    "name": "Grace Lopez",
    "email": "grace.lopez@example.org",
    "phone": "555-123-4567",
    "address": {
      "street": "4821 Maple Avenue",
      "city": "North Judyton",
      "state": "California",
      "zip": "94103",
      "country": "United States of America"
    },
    "avatar": "https://api.dicebear.com/9.x/identicon/svg?seed=Grace+Lopez"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Full name of the generated user |
| `email` | string | Email address of the generated user |
| `phone` | string | Phone number of the generated user |
| `address.street` | string | Street address |
| `address.city` | string | City name |
| `address.state` | string | State or region |
| `address.zip` | string | Postal / ZIP code |
| `address.country` | string | Country name |
| `avatar` | string | URL to a unique identicon avatar for the generated user (DiceBear) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `500` |  | Internal server error |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/technology/random-user \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/random-user"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
user = response.json()['data']
print(f"Generated user: {user['name']} <{user['email']}>")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/random-user',
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(`Generated user: ${data.name} <${data.email}>`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/random-user')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

user = JSON.parse(response.body)['data']
puts "Generated user: #{user['name']} <#{user['email']}>"
```

## `POST /v1/technology/random-user/batch`

Returns multiple randomly generated fake user profiles in a single request. Each call consumes count units of quota. Maximum 50 users per request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `count` | integer | Yes | Number of users to generate (min: 1, max: 50). |

### Request

```json
{
  "count": 2
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "name": "Grace Lopez",
        "email": "grace.lopez@example.org",
        "phone": "555-123-4567",
        "address": {
          "street": "4821 Maple Avenue",
          "city": "North Judyton",
          "state": "California",
          "zip": "94103",
          "country": "United States of America"
        },
        "avatar": "https://api.dicebear.com/9.x/identicon/svg?seed=Grace+Lopez"
      },
      {
        "name": "John Smith",
        "email": "john.smith@example.com",
        "phone": "555-987-6543",
        "address": {
          "street": "12 Oak Street",
          "city": "Springfield",
          "state": "Illinois",
          "zip": "62701",
          "country": "United States of America"
        },
        "avatar": "https://api.dicebear.com/9.x/identicon/svg?seed=John+Smith"
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Ordered list of generated user profiles. Same fields as the single-user endpoint. |
| `total` | integer | Number of users returned. Matches the requested count. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  | count is missing, less than 1, or greater than 50 |
| `400` |  | Request body is malformed or not valid JSON |
| `500` |  | Internal server error |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/random-user/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 5}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/random-user/batch"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.post(url, headers=headers, json={"count": 5})
users = response.json()['data']['results']
for user in users:
    print(f"Generated user: {user['name']} <{user['email']}>")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/random-user/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ count: 5 })
  }
);

const { data } = await response.json();
data.results.forEach(user => {
  console.log(`Generated user: ${user.name} <${user.email}>`);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/random-user/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { count: 5 }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

users = JSON.parse(response.body)['data']['results']
users.each { |user| puts "Generated user: #{user['name']} <#{user['email']}>" }
```

---
# Base64 Encode / Decode

Encode strings to Base64 and decode Base64 back to plain text. Supports standard and URL-safe (base64url) variants.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 800 ms |
| p95 | 993 ms |
| p99 | 1037 ms |

## `POST /v1/technology/base64/encode`

Encode a plain-text string to Base64

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `value` | string | Yes | The string to encode |
| `variant` | string | No | Encoding variant: standard (default) or url (URL-safe base64url) |

### Response Example

```json
{
  "data": {
    "result": "SGVsbG8sIHdvcmxkIQ=="
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `result` | string | The Base64-encoded output |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or empty value field |
| `422` |  | Validation constraint on the variant field (must be standard or url) |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/base64/encode \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "Hello, world!"}'

# URL-safe variant
curl -X POST https://requiems.xyz/v1/technology/base64/encode \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "Hello, world!", "variant": "url"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base64/encode"
headers = {"requiems-api-key": "YOUR_API_KEY"}
payload = {"value": "Hello, world!"}

response = requests.post(url, json=payload, headers=headers)
print(response.json()["data"]["result"])  # SGVsbG8sIHdvcmxkIQ==
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/base64/encode', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ value: 'Hello, world!' })
});

const { data } = await response.json();
console.log(data.result); // SGVsbG8sIHdvcmxkIQ==
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base64/encode')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { value: 'Hello, world!' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)['data']['result']  # SGVsbG8sIHdvcmxkIQ==
```

## `POST /v1/technology/base64/decode`

Decode a Base64-encoded string back to plain text

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `value` | string | Yes | The Base64-encoded string to decode |
| `variant` | string | No | Encoding variant: standard (default) or url (URL-safe base64url) |

### Response Example

```json
{
  "data": {
    "result": "Hello, world!"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `result` | string | The decoded plain-text output |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Missing or empty value field |
| `422` |  | The value is not valid Base64 and cannot be decoded |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/base64/decode \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "SGVsbG8sIHdvcmxkIQ=="}'

# URL-safe variant
curl -X POST https://requiems.xyz/v1/technology/base64/decode \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "SGVsbG8sIHdvcmxkIQ==", "variant": "url"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base64/decode"
headers = {"requiems-api-key": "YOUR_API_KEY"}
payload = {"value": "SGVsbG8sIHdvcmxkIQ=="}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

if response.status_code == 200:
    print(result["data"]["result"])  # Hello, world!
else:
    print(f"Error: {result['error']}")  # invalid_base64
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/base64/decode', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ value: 'SGVsbG8sIHdvcmxkIQ==' })
});

if (response.ok) {
  const { data } = await response.json();
  console.log(data.result); // Hello, world!
} else {
  const err = await response.json();
  console.error(err.error); // invalid_base64
}
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base64/decode')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { value: 'SGVsbG8sIHdvcmxkIQ==' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

body = JSON.parse(response.body)
if response.code == '200'
  puts body['data']['result']  # Hello, world!
else
  puts body['error']  # invalid_base64
end
```

## `POST /v1/technology/base64/encode/batch`

Encode multiple strings to Base64 in a single request

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `values` | array<string> | Yes | List of values to encode |
| `variant` | string | No | Encoding variant (standard or url) |

### Response Example

```json
{
  "data": {
    "results": [
      {
        "result": "SGVsbG8="
      },
      {
        "result": "V29ybGQ="
      }
    ],
    "total": 2
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Encoded results |
| `total` | integer | Number of processed items |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  | Invalid variant or values list size outside 1-50 |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/technology/base64/encode/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values":["Hello","World"],"variant":"standard"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base64/encode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = { "values": ["Hello", "World"], "variant": "standard" }
response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/base64/encode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 'values': ["Hello", "World"], 'variant': "standard" })
});
const { data } = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base64/encode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { "values" => ["Hello", "World"], "variant" => "standard" }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']
```

## `POST /v1/technology/base64/decode/batch`

Decode multiple Base64 strings in a single request

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `values` | array<string> | Yes | List of Base64 strings to decode |
| `variant` | string | No | Encoding variant (standard or url) |

### Response Example

```json
{
  "data": {
    "results": [
      {
        "result": "Hello"
      },
      {
        "result": "World"
      }
    ],
    "total": 2
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Decoded results |
| `total` | integer | Number of processed items |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `422` |  | Invalid variant or values list size outside 1-50 |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/technology/base64/decode/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values":["SGVsbG8=","V29ybGQ="],"variant":"standard"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base64/decode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = { "values": ["SGVsbG8=", "V29ybGQ="], "variant": "standard" }
response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/base64/decode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 'values': ["SGVsbG8=", "V29ybGQ="], 'variant': "standard" })
});
const { data } = await response.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base64/decode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { "values" => ["SGVsbG8=", "V29ybGQ="], "variant" => "standard" }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']
```

---
# Number Base Conversion

Convert integers between binary (base 2), octal (base 8), decimal (base 10), and hexadecimal (base 16).

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 775 ms |
| p95 | 896 ms |
| p99 | 1050 ms |

## `GET /v1/technology/base`

Convert an integer from one number base to another.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | integer | Yes | Source base (2, 8, 10, or 16) |
| `to` | integer | Yes | Target base (2, 8, 10, or 16) |
| `value` | string | Yes | The number as a string. Accepts optional prefixes: 0x (hex), 0b (binary), 0o (octal). |

### Response Example

```json
{
  "data": {
    "input": "255",
    "from": 10,
    "to": 16,
    "result": "ff"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `input` | string | The original value as provided in the request |
| `from` | integer | The source base |
| `to` | integer | The target base |
| `result` | string | The converted value in the target base |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | A required parameter is missing, the base is not one of 2/8/10/16, or value is not valid for the given base. |

### Code Examples

**Curl**

```curl
# Decimal to hex
curl "https://requiems.xyz/v1/technology/base?from=10&to=16&value=255" \
  -H "requiems-api-key: YOUR_API_KEY"

# Hex to binary (using 0x prefix)
curl "https://requiems.xyz/v1/technology/base?from=16&to=2&value=0xff" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"from": 10, "to": 16, "value": "255"}

response = requests.get(url, params=params, headers=headers)
print(response.json()["data"]["result"])  # ff
```

**Javascript**

```javascript
const params = new URLSearchParams({ from: 10, to: 16, value: '255' });
const response = await fetch(
  `https://requiems.xyz/v1/technology/base?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.result); // ff
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base')
uri.query = URI.encode_www_form(from: 10, to: 16, value: '255')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)['data']['result']  # ff
```

## `POST /v1/technology/base/batch`

Convert up to 50 numbers between bases in a single request. Results are returned in input order. Per-item errors are reported inline.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | array<object> | Yes | List of conversion requests (1–50 items). |
| `items[].from` | integer | Yes | Source base (2, 8, 10, or 16). |
| `items[].to` | integer | Yes | Target base (2, 8, 10, or 16). |
| `items[].value` | string | Yes | The number as a string. Accepts optional prefixes: 0x (hex), 0b (binary), 0o (octal). |

### Request

```json
{
  "items": [
    { "from": 10, "to": 16, "value": "255" },
    { "from": 2,  "to": 10, "value": "1111" }
  ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "from": 10, "to": 16, "input": "255",  "result": "ff" },
      { "from": 2,  "to": 10, "input": "1111", "result": "15" }
    ],
    "total": 2
  },
  "metadata": { "timestamp": "2026-01-01T00:00:00Z" }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Per-item results in input order. |
| `results[].from` | integer | The source base used for conversion. |
| `results[].to` | integer | The target base used for conversion. |
| `results[].input` | string | The original value as provided in the request. |
| `results[].result` | string | The converted value in the target base (omitted on error). |
| `results[].error` | string | Error message if this item failed (omitted on success). |
| `total` | integer | Total number of items processed. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The items array is missing, empty, or exceeds 50 items. |
| `bad_request` | 400 | The request body is missing or malformed. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/technology/base/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"from": 10, "to": 16, "value": "255"}, {"from": 2, "to": 10, "value": "1111"}]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/base/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"from": 10, "to": 16, "value": "255"},
        {"from": 2,  "to": 10, "value": "1111"}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    print(item.get("result") or item.get("error"))
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/base/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { from: 10, to: 16, value: '255' },
      { from: 2,  to: 10, value: '1111' }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => console.log(item.result ?? item.error));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/base/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { from: 10, to: 16, value: '255' },
    { from: 2,  to: 10, value: '1111' }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each { |item| puts item['result'] || item['error'] }
```

---
# Color Format Conversion

Convert color values between HEX, RGB, HSL, and CMYK formats. Every response includes all four representations so you never need to call more than once.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 780 ms |
| p95 | 890 ms |
| p99 | 1099 ms |

## `GET /v1/technology/color`

Convert a color value from one format to another. The response always includes all four formats.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | Source color format: hex, rgb, hsl, or cmyk |
| `to` | string | Yes | Target color format: hex, rgb, hsl, or cmyk |
| `value` | string | Yes | Color value in the source format (e.g. #ff5733, rgb(255,87,51), hsl(11,100%,60%), cmyk(0%,66%,80%,0%)) |

### Response Example

```json
{
  "data": {
    "input": "#ff5733",
    "result": "hsl(11, 100%, 60%)",
    "formats": {
      "hex": "#ff5733",
      "rgb": "rgb(255, 87, 51)",
      "hsl": "hsl(11, 100%, 60%)",
      "cmyk": "cmyk(0%, 66%, 80%, 0%)"
    }
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `input` | string | The original value passed in the value parameter |
| `result` | string | The color expressed in the requested to format |
| `formats.hex` | string | HEX representation (#rrggbb) |
| `formats.rgb` | string | RGB representation (rgb(r, g, b)) |
| `formats.hsl` | string | HSL representation (hsl(h, s%, l%)) |
| `formats.cmyk` | string | CMYK representation (cmyk(c%, m%, y%, k%)) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | One or more of from, to, or value parameters is missing or the from/to value is not one of: hex, rgb, hsl, cmyk. |
| `invalid_color` | 422 | The value cannot be parsed in the specified from format. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
# HEX to HSL
curl "https://requiems.xyz/v1/technology/color?from=hex&to=hsl&value=%23ff5733" \
  -H "requiems-api-key: YOUR_API_KEY"

# RGB to CMYK
curl "https://requiems.xyz/v1/technology/color?from=rgb&to=cmyk&value=rgb(255%2C87%2C51)" \
  -H "requiems-api-key: YOUR_API_KEY"

# HSL to HEX
curl "https://requiems.xyz/v1/technology/color?from=hsl&to=hex&value=hsl(120%2C100%25%2C50%25)" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/color"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"from": "hex", "to": "hsl", "value": "#ff5733"}

response = requests.get(url, params=params, headers=headers)
data = response.json()["data"]

print(data["result"])          # hsl(11, 100%, 60%)
print(data["formats"]["rgb"])  # rgb(255, 87, 51)
```

**Javascript**

```javascript
const params = new URLSearchParams({
  from: 'hex',
  to: 'hsl',
  value: '#ff5733'
});

const response = await fetch(
  `https://requiems.xyz/v1/technology/color?${params}`,
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);

const { data } = await response.json();
console.log(data.result);           // hsl(11, 100%, 60%)
console.log(data.formats.cmyk);     // cmyk(0%, 66%, 80%, 0%)
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/color')
uri.query = URI.encode_www_form(from: 'hex', to: 'hsl', value: '#ff5733')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['result']            # hsl(11, 100%, 60%)
puts data['formats']['hex']    # #ff5733
```

---
# Unit Conversion

Convert between units of measurement and discover available conversion types. Supports length, weight, volume, temperature, area, and speed conversions.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 8 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 820 ms |
| p95 | 861 ms |
| p99 | 861 ms |

## `GET /v1/technology/convert`

Convert a value from one unit to another

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | Source unit key (e.g. miles, kg, c) |
| `to` | string | Yes | Target unit key (e.g. km, lb, f) |
| `value` | number | Yes | Numeric value to convert |

### Response Example

```json
{
  "data": {
    "from": "miles",
    "to": "km",
    "input": 10,
    "result": 16.09344,
    "formula": "miles × 1.609344"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | Source unit key |
| `to` | string | Target unit key |
| `input` | number | The original input value |
| `result` | number | The converted value (rounded to 6 decimal places) |
| `formula` | string | Human-readable conversion formula |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/technology/convert?from=miles&to=km&value=10" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/convert"
params = {"from": "miles", "to": "km", "value": 10}
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const params = new URLSearchParams({ from: 'miles', to: 'km', value: 10 });
const response = await fetch(`https://requiems.xyz/v1/technology/convert?${params}`, {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(data.result); // 16.09344
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/convert')
uri.query = URI.encode_www_form(from: 'miles', to: 'km', value: 10)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['result'] # 16.09344
```

## `GET /v1/technology/convert/units`

Returns all available unit conversion types grouped by measurement category

### Response Example

```json
{
  "data": {
    "length": ["cm", "ft", "in", "km", "m", "miles", "mm", "nmi", "yd"],
    "weight": ["g", "kg", "lb", "mg", "oz", "stone", "t"],
    "volume": ["cup", "fl_oz", "gal", "l", "ml", "pt", "qt", "tbsp", "tsp"],
    "temperature": ["c", "f", "k"],
    "area": ["acre", "cm2", "ft2", "ha", "in2", "km2", "m2", "mm2", "yd2"],
    "speed": ["km_h", "knots", "m_s", "mph"]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `length` | array<string> | Available length units: millimeter (mm), centimeter (cm), meter (m), kilometer (km), inch (in), foot (ft), yard (yd), mile (miles), nautical mile (nmi) |
| `weight` | array<string> | Available weight units: milligram (mg), gram (g), kilogram (kg), metric ton (t), ounce (oz), pound (lb), stone (stone) |
| `volume` | array<string> | Available volume units: milliliter (ml), liter (l), teaspoon (tsp), tablespoon (tbsp), fluid ounce (fl_oz), cup (cup), pint (pt), quart (qt), gallon (gal) |
| `temperature` | array<string> | Available temperature units: celsius (c), fahrenheit (f), kelvin (k) |
| `area` | array<string> | Available area units: square millimeter (mm2), square centimeter (cm2), square meter (m2), square kilometer (km2), square inch (in2), square foot (ft2), square yard (yd2), acre (acre), hectare (ha) |
| `speed` | array<string> | Available speed units: meters per second (m_s), kilometers per hour (km_h), miles per hour (mph), knots (knots) |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/technology/convert/units \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/convert/units"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
units = response.json()['data']

# Print all length units
print("Length units:", units['length'])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/technology/convert/units', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();

// Build a dropdown with length units
data.length.forEach(unit => {
  console.log(`<option value="${unit}">${unit}</option>`);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/convert/units')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

units = JSON.parse(response.body)['data']
puts "Temperature units: #{units['temperature'].join(', ')}"
```

## `POST /v1/technology/convert/batch`

convert up to 50 unit conversion operations in a single request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `operations` | array<object> | Yes | Array of operations to convert (min: 1, max: 50). |

### Request

```json
{
  "operations": [
    {
      "from": "kg",
      "to": "lb",
      "value": 10
    },
    {
      "from": "c",
      "to": "f",
      "value": 5
    }
 ]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "from": "kg",
        "to": "lb",
        "success": true,
        "data": {
          "from": "kg",
          "to": "lb",
          "input": 10,
          "result": 22.046244,
          "formula": "kg × 2.204624"
        }
      },
      {
        "from": "c",
        "to": "f",
        "success": true,
        "data": {
          "from": "c",
          "to": "f",
          "input": 5,
          "result": 41,
          "formula": "°C × 9/5 + 32"
        }
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-05-15T21:52:05Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of unit conversion results returned in the same order as the input operations. |
| `results[].from` | string | Source unit used for the conversion. |
| `results[].to` | string | Target unit used for the conversion. |
| `results[].success` | boolean | Indicates whether the conversion operation was successful. |
| `results[].error` | string | Error message if the conversion failed. Empty when success is true. |
| `results[].data` | object | Conversion result details. Contains empty values when the conversion fails. |
| `results[].data.from` | string | Source unit. |
| `results[].data.to` | string | Target unit. |
| `results[].data.input` | number | Original numeric value provided for conversion. |
| `results[].data.result` | number | Converted numeric result. |
| `results[].data.formula` | string | Formula or conversion factor used to calculate the result. |
| `total` | integer | Total number of conversion results returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The operations array is missing, empty, or contains more than 50 items. |
| `bad_request` | 400 | Invalid JSON, malformed request body, or unexpected field types. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/technology/convert/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "from": "kg",
        "to": "lb",
        "value": 10
      },
      {
        "from": "c",
        "to": "f",
        "value": 5
      }
    ]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/convert/batch"

headers = {
  "requiems-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

payload = {
  "operations": [
    {
      "from": "kg",
      "to": "lb",
      "value": 10
    },
    {
      "from": "c",
      "to": "f",
      "value": 5
    }
  ]
}

response = requests.post(url, headers=headers, json=payload)

for item in response.json()["data"]["results"]:
  print(item["from"], "->", item["to"])

  if item["success"]:
    print("Result:", item["data"]["result"])
    print("Formula:", item["data"]["formula"])
  else:
    print("Error:", item["error"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/technology/convert/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operations: [
        {
          from: 'kg',
          to: 'lb',
          value: 10
        },
        {
          from: 'c',
          to: 'f',
          value: 5
        }
      ]
    })
  }
);

const { data } = await response.json();

data.results.forEach(item => {
  console.log(item.from, '->', item.to);

  if (item.success) {
    console.log('Result:', item.data.result);
    console.log('Formula:', item.data.formula);
  } else {
    console.log('Error:', item.error);
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/convert/batch')

request = Net::HTTP::Post.new(uri)

request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  operations: [
    {
      from: 'kg',
      to: 'lb',
      value: 10
    },
    {
      from: 'c',
      to: 'f',
      value: 5
    }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |item|
  puts "#{item['from']} -> #{item['to']}"

  if item['success']
    puts "Result: #{item['data']['result']}"
    puts "Formula: #{item['data']['formula']}"
  else
    puts "Error: #{item['error']}"
  end
end
```

---
# Data Format Conversion

Convert structured data between JSON, YAML, CSV, XML, and TOML in a single API call. Accepts any supported format as input and returns the content serialized in the target format.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 775 ms |
| p95 | 893 ms |
| p99 | 1097 ms |

## `POST /v1/technology/format`

Convert content from one structured data format to another. Supported formats: json, yaml, csv, xml, toml.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | Source format. One of: json, yaml, csv, xml, toml |
| `to` | string | Yes | Target format. One of: json, yaml, csv, xml, toml |
| `content` | string | Yes | The content to convert, serialized as a string in the source format. |

### Request

```json
{
  "from": "json",
  "to": "yaml",
  "content": "{\"name\": \"Alice\", \"age\": 30}"
}
```

### Response Example

```json
{
  "data": {
    "result": "age: 30\nname: Alice\n"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `result` | string | The converted content serialized in the target format. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | One of from, to, or content is missing, or from/to is not one of the supported format values. |
| `invalid_json` | 422 | The content field is not valid JSON (when from is json). |
| `invalid_yaml` | 422 | The content field is not valid YAML (when from is yaml). |
| `invalid_csv` | 422 | The content field is not valid CSV, or a row has more columns than the header (when from is csv). |
| `invalid_xml` | 422 | The content field is not valid XML (when from is xml). |
| `invalid_toml` | 422 | The content field is not valid TOML (when from is toml). |
| `conversion_error` | 422 | The data structure is incompatible with the target format (e.g. converting a JSON array to TOML, which requires a top-level object). |
| `content_too_large` | 413 | The content field exceeds the 512 KB limit. |

### Code Examples

**Curl**

```curl
# JSON → YAML
curl -X POST https://requiems.xyz/v1/technology/format \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"json","to":"yaml","content":"{\"name\":\"Alice\",\"age\":30}"}'

# CSV → JSON
curl -X POST https://requiems.xyz/v1/technology/format \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"csv","to":"json","content":"name,age\nAlice,30\nBob,25"}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/technology/format"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

# JSON → YAML
payload = {
    "from": "json",
    "to": "yaml",
    "content": '{"name": "Alice", "age": 30}',
}
response = requests.post(url, json=payload, headers=headers)
print(response.json()["data"]["result"])
# age: 30
# name: Alice

# CSV → JSON
csv_payload = {
    "from": "csv",
    "to": "json",
    "content": "name,age\nAlice,30\nBob,25",
}
response = requests.post(url, json=csv_payload, headers=headers)
print(response.json()["data"]["result"])
```

**Javascript**

```javascript
const url = 'https://requiems.xyz/v1/technology/format';
const headers = {
  'requiems-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json',
};

// JSON → YAML
const res = await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    from: 'json',
    to: 'yaml',
    content: JSON.stringify({ name: 'Alice', age: 30 }),
  }),
});

const { data } = await res.json();
console.log(data.result);
// age: 30
// name: Alice
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/technology/format')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  from: 'json',
  to: 'yaml',
  content: '{"name":"Alice","age":30}'
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)['data']['result']
# age: 30
# name: Alice
```

---
# Random Quotes

Get random inspirational quotes from famous people, thinkers, and leaders. Perfect for daily motivation, content generation, or adding wisdom to your applications.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 921 ms |
| p95 | 1075 ms |
| p99 | 1375 ms |

## `GET /v1/entertainment/quotes/random`

Returns a random inspirational quote with author attribution

### Response Example

```json
{
  "data": {
    "id": 42,
    "text": "The only way to do great work is to love what you do.",
    "author": "Steve Jobs"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique identifier for the quote |
| `text` | string | The quote text |
| `author` | string | Name of the person who said or wrote the quote |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `503` |  | No quotes available in the database |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/quotes/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/quotes/random"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
quote = response.json()['data']
print(f"{quote['text']} - {quote['author']}")
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/entertainment/quotes/random', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log(`${data.text} - ${data.author}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/quotes/random')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "#{data['text']} - #{data['author']}"
```

## `POST /v1/entertainment/quotes/random/batch`

Returns up to 50 random quotes in a single request. Each quote counts as one unit of usage.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `count` | integer | Yes | Number of random quotes to return. Between 1 and 50. |

### Request

```json
{
  "count": 5
}
```

### Response Example

```json
{
  "data": {
    "results": [
      { "id": 42, "text": "The only way to do great work is to love what you do.", "author": "Steve Jobs" },
      { "id": 7,  "text": "In the middle of every difficulty lies opportunity.", "author": "Albert Einstein" },
      { "id": 15, "text": "It does not matter how slowly you go as long as you do not stop.", "author": "Confucius" },
      { "id": 3,  "text": "Life is what happens when you're busy making other plans.", "author": "John Lennon" },
      { "id": 88, "text": "Spread love everywhere you go.", "author": "Mother Teresa" }
    ],
    "total": 5
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Array of random quotes, one per requested count. |
| `results[].id` | integer | Unique identifier for the quote. |
| `results[].text` | string | The quote text. |
| `results[].author` | string | Name of the person who said or wrote the quote. May be empty. |
| `total` | integer | Total number of quotes returned. Always equals the requested count. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  | Request body is missing or not valid JSON. |
| `422` |  | count is missing, less than 1, or greater than 50. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/entertainment/quotes/random/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 5}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/quotes/random/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"count": 5}

response = requests.post(url, json=payload, headers=headers)
for quote in response.json()['data']['results']:
    print(f"{quote['text']} - {quote['author']}")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/quotes/random/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ count: 5 })
  }
);
const { data } = await response.json();
data.results.forEach(q => console.log(`${q.text} - ${q.author}`));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/quotes/random/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { count: 5 }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |q|
  puts "#{q['text']} - #{q['author']}"
end
```

---
# Trivia

Get random trivia questions with multiple-choice answers. Filter by category and difficulty to target specific question pools.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 946 ms |
| p95 | 1206 ms |
| p99 | 1232 ms |

## `GET /v1/entertainment/trivia`

Returns a random trivia question with multiple-choice answers. Use the optional category and difficulty query parameters to filter the question pool.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Filter by category. One of: science, history, geography, sports, music, movies, literature, math, technology, nature. |
| `difficulty` | string | No | Filter by difficulty. One of: easy, medium, hard. |

### Response Example

```json
{
  "data": {
    "question": "What is the largest planet in our solar system?",
    "options": ["Earth", "Jupiter", "Saturn", "Mars"],
    "answer": "Jupiter",
    "category": "science",
    "difficulty": "easy"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `question` | string | The trivia question text |
| `options` | array<string> | Four multiple-choice answer options |
| `answer` | string | The correct answer — always one of the values in options |
| `category` | string | The category the question belongs to |
| `difficulty` | string | The difficulty level of the question (easy, medium, or hard) |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | An invalid category or difficulty value was provided |
| `not_found` | 404 | No questions match the given category and difficulty combination |
| `unauthorized` | 401 | Missing API key |
| `forbidden` | 403 | Invalid or revoked API key |

### Code Examples

**Curl**

```curl
# Random question (no filters)
curl "https://requiems.xyz/v1/entertainment/trivia" \
  -H "requiems-api-key: YOUR_API_KEY"

# Filtered by category and difficulty
curl "https://requiems.xyz/v1/entertainment/trivia?category=science&difficulty=medium" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/trivia"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"category": "science", "difficulty": "medium"}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]
print(data["question"])
print("Options:", data["options"])
print("Answer:", data["answer"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/trivia?category=science&difficulty=medium',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(data.question);
console.log('Options:', data.options);
console.log('Answer:', data.answer);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/trivia')
uri.query = URI.encode_www_form(category: 'science', difficulty: 'medium')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts data['question']
puts "Answer: #{data['answer']}"
```

## `POST /v1/entertainment/trivia/batch`

Returns up to 50 trivia questions in a single request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filters` | array<object> | Yes | Array of filters to get (min: 1, max: 50). |

### Request

```json
{
  "filters": [{"category": "sports", "difficulty": "easy"},{"category": "history", "difficulty": "medium"}]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "category": "sports",
        "difficulty": "easy",
        "data": {
          "question": "In which country did the ancient Olympic Games originate?",
          "options": [
            "Italy",
            "Turkey",
            "Greece",
            "Egypt"
          ],
          "answer": "Greece",
          "category": "sports",
          "difficulty": "easy"
        }
      },
      {
        "category": "history",
        "difficulty": "medium",
        "data": {
          "question": "In what year was the Magna Carta signed?",
          "options": [
            "1215",
            "1066",
            "1415",
            "1305"
          ],
          "answer": "1215",
          "category": "history",
          "difficulty": "medium"
        }
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-05-22T22:27:35Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of trivia questions returned in the same order as the input filters. |
| `results[].category` | string | The topic filter used to retrieve the trivia question. |
| `results[].difficulty` | string | The complexity level filter used to retrieve the trivia question. |
| `results[].error` | string | Describes why the question could not be retrieved for this filter. Omitted if the query was successful. |
| `results[].data` | object | The trivia question returned for this filter. Empty if the query failed. |
| `results[].data.question` | string | The trivia question text. |
| `results[].data.options` | array<string> | List of possible answers for the question. |
| `results[].data.answer` | string | The correct answer to the trivia question. |
| `results[].data.category` | string | The category the trivia question belongs to. |
| `results[].data.difficulty` | string | The difficulty level of the trivia question. |
| `total` | integer | Total number of trivia results returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The filters array is missing, empty, or contains more than 50 items. |
| `bad_request` | 400 | Invalid JSON, malformed request body, or unexpected field types. |
| `unauthorized` | 401 | Missing API key. |
| `forbidden` | 403 | Invalid or revoked API key. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/entertainment/trivia/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "category": "sports", "difficulty": "easy" },
      { "category": "history", "difficulty": "medium" }
    ]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/trivia/batch"

headers = {
  "requiems-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

payload = {
  "filters": [
    { "category": "sports", "difficulty": "easy" },
    { "category": "history", "difficulty": "medium" }
  ]
}

response = requests.post(url, headers=headers, json=payload)

for item in response.json()["data"]["results"]:
  print(item["category"], "-", item["difficulty"])
  if item.get("error"):
    print("Error:", item["error"])
  else:
    print("Question:", item["data"]["question"])
    print("Options:", item["data"]["options"])
    print("Answer:", item["data"]["answer"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/trivia/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      filters: [
        { category: 'sports', difficulty: 'easy' },
        { category: 'history', difficulty: 'medium' }
      ]
    })
  }
);

const { data } = await response.json();

data.results.forEach(item => {
  console.log(item.category, '-', item.difficulty);
  if (item.error) {
    console.log('Error:', item.error);
  } else {
    console.log('Question:', item.data.question);
    console.log('Options:', item.data.options);
    console.log('Answer:', item.data.answer);
  }
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/trivia/batch')

request = Net::HTTP::Post.new(uri)

request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  filters: [
    { category: 'sports', difficulty: 'easy' },
    { category: 'history', difficulty: 'medium' }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |item|
  puts "#{item['category']} - #{item['difficulty']}"
  if item['error']
    puts "Error: #{item['error']}"
  else
    puts "Question: #{item['data']['question']}"
    puts "Options: #{item['data']['options']}"
    puts "Answer: #{item['data']['answer']}"
  end
end
```

---
# Random Facts

Get random interesting facts from a curated database covering science, history, technology, nature, space, and food.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 943 ms |
| p95 | 1233 ms |
| p99 | 1266 ms |

## `GET /v1/entertainment/facts`

Returns a randomly selected fact, optionally filtered by category.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Filter by category. Valid values: science, history, technology, nature, space, food |

### Response Example

```json
{
  "data": {
    "fact": "Honey never spoils. Archaeologists have found 3,000-year-old honey in Egyptian tombs that was still perfectly edible.",
    "category": "science",
    "source": "National Geographic"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `fact` | string | The fact text |
| `category` | string | The category the fact belongs to |
| `source` | string | The source or publication the fact is attributed to |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `400` |  |  |

### Code Examples

**Curl**

```curl
# Random fact from any category
curl https://requiems.xyz/v1/entertainment/facts \
  -H "requiems-api-key: YOUR_API_KEY"

# Random science fact
curl "https://requiems.xyz/v1/entertainment/facts?category=science" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/facts"
headers = {"requiems-api-key": "YOUR_API_KEY"}

# Optional: filter by category
params = {"category": "space"}

response = requests.get(url, headers=headers, params=params)
data = response.json()['data']
print(f"[{data['category']}] {data['fact']} — {data['source']}")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/facts?category=history',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(`[${data.category}] ${data.fact} — ${data.source}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/facts')
uri.query = URI.encode_www_form(category: 'nature')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
puts "[#{data['category']}] #{data['fact']} — #{data['source']}"
```

---
# Emoji

Look up emoji by name, search by keyword, or get a random emoji. Each response includes the rendered glyph, CLDR snake_case name, Unicode category, and code-point.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 932 ms |
| p95 | 1041 ms |
| p99 | 1246 ms |

## `GET /v1/entertainment/emoji/random`

Returns a randomly selected emoji with its full metadata.

### Response Example

```json
{
  "data": {
    "emoji": "😀",
    "name": "grinning_face",
    "category": "Smileys & Emotion",
    "unicode": "U+1F600"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `emoji` | string | The rendered emoji glyph |
| `name` | string | CLDR short name in snake_case (e.g. grinning_face) |
| `category` | string | Unicode category (e.g. Smileys & Emotion, Animals & Nature) |
| `unicode` | string | Unicode code-point in U+XXXX notation (e.g. U+1F600) |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/emoji/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/emoji/random"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/emoji/random',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.emoji, data.data.name);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/emoji/random')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['emoji']
```

## `GET /v1/entertainment/emoji/search`

Search for emojis whose name or category contains the given query string (case-insensitive). Returns a list of all matches.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | Yes | Search term to match against emoji names and categories (e.g. happy, heart, food) |

### Response Example

```json
{
  "data": {
    "items": [
      {
        "emoji": "😄",
        "name": "grinning_face_with_smiling_eyes",
        "category": "Smileys & Emotion",
        "unicode": "U+1F604"
      }
    ],
    "total": 1
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `items` | array<object> | List of matching emoji objects |
| `total` | integer | Total number of matches |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The q query parameter is missing or empty. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/entertainment/emoji/search?q=happy" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/emoji/search"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"q": "happy"}

response = requests.get(url, headers=headers, params=params)
data = response.json()
for emoji in data['data']['items']:
    print(emoji['emoji'], emoji['name'])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/emoji/search?q=happy',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
data.data.items.forEach(e => console.log(e.emoji, e.name));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/emoji/search')
uri.query = URI.encode_www_form(q: 'happy')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
data['data']['items'].each { |e| puts "#{e['emoji']} #{e['name']}" }
```

## `GET /v1/entertainment/emoji/{name}`

Returns a specific emoji by its CLDR snake_case name. The name is case-insensitive.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | CLDR snake_case emoji name (e.g. grinning_face, thumbs_up) |

### Response Example

```json
{
  "data": {
    "emoji": "😀",
    "name": "grinning_face",
    "category": "Smileys & Emotion",
    "unicode": "U+1F600"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `emoji` | string | The rendered emoji glyph |
| `name` | string | CLDR short name in snake_case |
| `category` | string | Unicode category |
| `unicode` | string | Unicode code-point in U+XXXX notation |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No emoji found with the given name. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/emoji/grinning_face \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/emoji/grinning_face"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/emoji/grinning_face',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.emoji, data.data.unicode);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/emoji/grinning_face')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['emoji']
```

---
# Horoscope

Get daily horoscope readings for all 12 zodiac signs. Each reading is deterministically generated per sign per day.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 890 ms |
| p95 | 1095 ms |
| p99 | 1210 ms |

## `GET /v1/entertainment/horoscope/{sign}`

Returns a daily horoscope reading for the specified zodiac sign.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sign` | string | Yes | Zodiac sign (case-insensitive). Supported values: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces |

### Response Example

```json
{
  "data": {
    "sign": "aries",
    "date": "2024-12-15",
    "horoscope": "Today is a great day for new beginnings. Trust your instincts and take that first step toward your goals.",
    "lucky_number": 7,
    "mood": "energetic"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `sign` | string | Normalized zodiac sign (lowercase) |
| `date` | string | Today's date in YYYY-MM-DD format (UTC) |
| `horoscope` | string | Daily horoscope reading |
| `lucky_number` | integer | Lucky number for the day (1-99) |
| `mood` | string | Suggested mood for the day |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/horoscope/aries \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/horoscope/aries"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/horoscope/aries',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.horoscope);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/horoscope/aries')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['horoscope']
```

## `POST /v1/entertainment/horoscope/batch`

Returns up to 12 daily horoscopes in a single request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signs` | array<string> | Yes | Array of signs to get (min: 1, max: 12). Allowed values: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces. |

### Request

```json
{
  "signs": ["taurus","cancer","libra"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "sign": "taurus",
        "date": "2026-05-21",
        "horoscope": "Your patience will be rewarded. Take time to reflect before making important decisions today.",
        "lucky_number": 26,
        "mood": "reflective"
      },
      {
        "sign": "cancer",
        "date": "2026-05-21",
        "horoscope": "Your patience will be rewarded. Take time to reflect before making important decisions today.",
        "lucky_number": 2,
        "mood": "reflective"
      },
      {
        "sign": "libra",
        "date": "2026-05-21",
        "horoscope": "Rest and self-care are essential today. Taking care of yourself enables you to take care of others.",
        "lucky_number": 82,
        "mood": "peaceful"
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-05-21T04:09:20Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | List of daily horoscopes returned in the same order as the input signs. |
| `results[].sign` | string | Zodiac sign the horoscope corresponds to. |
| `results[].date` | string | Date the horoscope is for, in YYYY-MM-DD format. |
| `results[].horoscope` | string | Daily horoscope reading for the given sign. |
| `results[].lucky_number` | integer | Lucky number for the given sign on that date. |
| `results[].mood` | string | Predicted mood for the given sign on that date. |
| `total` | integer | Total number of horoscopes returned. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `validation_failed` | 422 | The signs array is missing, empty, or contains more than 12 items, or includes unsupported sign values. |
| `bad_request` | 400 | Invalid JSON, malformed request body, or unexpected field types. |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/entertainment/horoscope/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signs": [
      "taurus",
      "cancer",
      "libra"
    ]
  }'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/horoscope/batch"

headers = {
  "requiems-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

payload = {
  "signs": [
    "taurus",
    "cancer",
    "libra"
  ]
}

response = requests.post(url, headers=headers, json=payload)

for item in response.json()["data"]["results"]:
  print(item["sign"], "-", item["date"])
  print("Horoscope:", item["horoscope"])
  print("Mood:", item["mood"])
  print("Lucky number:", item["lucky_number"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/horoscope/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      signs: [
        'taurus',
        'cancer',
        'libra'
      ]
    })
  }
);

const { data } = await response.json();

data.results.forEach(item => {
  console.log(item.sign, '-', item.date);
  console.log('Horoscope:', item.horoscope);
  console.log('Mood:', item.mood);
  console.log('Lucky number:', item.lucky_number);
});
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/horoscope/batch')

request = Net::HTTP::Post.new(uri)

request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'

request.body = {
  signs: [
    'taurus',
    'cancer',
    'libra'
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |item|
  puts "#{item['sign']} - #{item['date']}"
  puts "Horoscope: #{item['horoscope']}"
  puts "Mood: #{item['mood']}"
  puts "Lucky number: #{item['lucky_number']}"
end
```

---
# Sudoku

Generate Sudoku puzzles of varying difficulty levels. Each response includes the puzzle grid (with 0 for empty cells) and the complete solution.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 903 ms |
| p95 | 992 ms |
| p99 | 1022 ms |

## `POST /v1/entertainment/sudoku/batch`

Generate up to 20 Sudoku puzzles in a single request. Results are returned in the same order as the input array. Each puzzle in the batch counts as one unit of API usage.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `puzzles` | array<string> | Yes | Array of difficulty levels to generate (min: 1, max: 20). Each must be one of: easy, medium, hard. |

### Request

```json
{
  "puzzles": ["easy", "hard"]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "difficulty": "easy",
        "puzzle": [
          [5, 3, 0, 0, 7, 0, 0, 0, 0],
          [6, 0, 0, 1, 9, 5, 0, 0, 0],
          [0, 9, 8, 0, 0, 0, 0, 6, 0],
          [8, 0, 0, 0, 6, 0, 0, 0, 3],
          [4, 0, 0, 8, 0, 3, 0, 0, 1],
          [7, 0, 0, 0, 2, 0, 0, 0, 6],
          [0, 6, 0, 0, 0, 0, 2, 8, 0],
          [0, 0, 0, 4, 1, 9, 0, 0, 5],
          [0, 0, 0, 0, 8, 0, 0, 7, 9]
        ],
        "solution": [
          [5, 3, 4, 6, 7, 8, 9, 1, 2],
          [6, 7, 2, 1, 9, 5, 3, 4, 8],
          [1, 9, 8, 3, 4, 2, 5, 6, 7],
          [8, 5, 9, 7, 6, 1, 4, 2, 3],
          [4, 2, 6, 8, 5, 3, 7, 9, 1],
          [7, 1, 3, 9, 2, 4, 8, 5, 6],
          [9, 6, 1, 5, 3, 7, 2, 8, 4],
          [2, 8, 7, 4, 1, 9, 6, 3, 5],
          [3, 4, 5, 2, 8, 6, 1, 7, 9]
        ]
      }
    ],
    "total": 1
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Generated puzzles in the same order as the input array. Each item has the same fields as the single-puzzle endpoint. |
| `results[].difficulty` | string | The difficulty level of the puzzle (easy, medium, or hard) |
| `results[].puzzle` | array<object> | 9×9 grid as an array of 9 rows, each row an array of 9 integers — 0 means an empty cell to be filled in |
| `results[].solution` | array<object> | 9×9 grid as an array of 9 rows, each row an array of 9 integers — complete, valid solution |
| `total` | integer | Number of puzzles returned. Matches the length of the input array. |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The request body is missing or contains malformed JSON. |
| `validation_failed` | 422 | The puzzles array is missing, empty, exceeds 20 items, or contains a value other than easy, medium, or hard. |
| `unauthorized` | 401 | Missing API key |
| `forbidden` | 403 | Invalid or revoked API key |

### Code Examples

**Curl**

```curl
curl -X POST "https://requiems.xyz/v1/entertainment/sudoku/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"puzzles":["easy","medium","hard"]}'
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/sudoku/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"puzzles": ["easy", "medium", "hard"]}

response = requests.post(url, headers=headers, json=payload)
for puzzle in response.json()["data"]["results"]:
    print(puzzle["difficulty"], puzzle["puzzle"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/sudoku/batch',
  {
    method: 'POST',
    headers: {
      'requiems-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ puzzles: ['easy', 'medium', 'hard'] })
  }
);

const { data } = await response.json();
data.results.forEach(p => console.log(p.difficulty, p.puzzle));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/sudoku/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { puzzles: ['easy', 'medium', 'hard'] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

JSON.parse(response.body)['data']['results'].each do |p|
  puts "#{p['difficulty']}: #{p['puzzle'].inspect}"
end
```

## `GET /v1/entertainment/sudoku`

Returns a randomly generated Sudoku puzzle and its solution. Difficulty defaults to medium when not specified.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `difficulty` | string | No | Puzzle difficulty level. One of: easy, medium, hard. Defaults to medium. |

### Response Example

```json
{
  "data": {
    "difficulty": "hard",
    "puzzle": [
      [5, 3, 0, 0, 7, 0, 0, 0, 0],
      [6, 0, 0, 1, 9, 5, 0, 0, 0],
      [0, 9, 8, 0, 0, 0, 0, 6, 0],
      [8, 0, 0, 0, 6, 0, 0, 0, 3],
      [4, 0, 0, 8, 0, 3, 0, 0, 1],
      [7, 0, 0, 0, 2, 0, 0, 0, 6],
      [0, 6, 0, 0, 0, 0, 2, 8, 0],
      [0, 0, 0, 4, 1, 9, 0, 0, 5],
      [0, 0, 0, 0, 8, 0, 0, 7, 9]
    ],
    "solution": [
      [5, 3, 4, 6, 7, 8, 9, 1, 2],
      [6, 7, 2, 1, 9, 5, 3, 4, 8],
      [1, 9, 8, 3, 4, 2, 5, 6, 7],
      [8, 5, 9, 7, 6, 1, 4, 2, 3],
      [4, 2, 6, 8, 5, 3, 7, 9, 1],
      [7, 1, 3, 9, 2, 4, 8, 5, 6],
      [9, 6, 1, 5, 3, 7, 2, 8, 4],
      [2, 8, 7, 4, 1, 9, 6, 3, 5],
      [3, 4, 5, 2, 8, 6, 1, 7, 9]
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `difficulty` | string | The difficulty level of the returned puzzle (easy, medium, or hard) |
| `puzzle` | array<object> | 9×9 grid as an array of 9 rows, each row an array of 9 integers — 0 means an empty cell to be filled in |
| `solution` | array<object> | 9×9 grid as an array of 9 rows, each row an array of 9 integers — complete, valid solution |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The difficulty parameter is not one of easy, medium, or hard |
| `unauthorized` | 401 | Missing API key |
| `forbidden` | 403 | Invalid or revoked API key |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/entertainment/sudoku?difficulty=hard" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/sudoku"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"difficulty": "hard"}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data["data"]["puzzle"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/sudoku?difficulty=hard',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(data.puzzle);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/sudoku')
uri.query = URI.encode_www_form(difficulty: 'hard')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['puzzle'].inspect
```

---
# Dad Jokes

Get a random dad joke. Classic groan-worthy puns and wholesome humor, served one at a time.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 921 ms |
| p95 | 1037 ms |
| p99 | 1126 ms |

## `GET /v1/entertainment/jokes/dad`

Returns a randomly selected dad joke from the collection.

### Response Example

```json
{
  "data": {
    "id": "joke_7",
    "joke": "Why don't scientists trust atoms? Because they make up everything!"
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Stable identifier for the joke (e.g. "joke_7") |
| `joke` | string | The full text of the dad joke |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `unauthorized` | 401 | Missing API key |
| `forbidden` | 403 | Invalid or revoked API key |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/jokes/dad \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/jokes/dad"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json()["data"]["joke"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/jokes/dad',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(data.joke);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/jokes/dad')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['joke']
```

---
# Chuck Norris Facts

Get a random Chuck Norris fact from a curated built-in database. Every call returns a different fact selected with a cryptographically secure random number generator.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 969 ms |
| p95 | 1137 ms |
| p99 | 1249 ms |

## `GET /v1/entertainment/chuck-norris`

Returns a randomly selected Chuck Norris fact from the built-in database.

### Response Example

```json
{
  "data": {
    "id": "cn_0",
    "fact": "Chuck Norris can divide by zero."
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique fact identifier in the format cn_<index> (e.g. cn_0, cn_7) |
| `fact` | string | The Chuck Norris fact text |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/chuck-norris \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/chuck-norris"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
result = response.json()['data']
print(f"[{result['id']}] {result['fact']}")
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/entertainment/chuck-norris',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(`[${data.id}] ${data.fact}`);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/chuck-norris')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)['data']
puts "[#{result['id']}] #{result['fact']}"
```

---
# Random Advice

Get random pieces of advice and wisdom for inspiration, daily motivation, or content generation.

**Base URL:** `https://requiems.xyz`

## Performance

Measured against production with 50 samples (last updated 2026-04-20).

| Metric | Value |
|--------|-------|
| p50 (median) | 908 ms |
| p95 | 1082 ms |
| p99 | 1173 ms |

## `GET /v1/entertainment/advice`

Returns a random piece of advice

### Response Example

```json
{
  "data": {
    "id": 42,
    "advice": "Don't compare yourself to others. Compare yourself to the person you were yesterday."
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique identifier for the advice |
| `advice` | string | A random piece of advice |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/entertainment/advice \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/entertainment/advice"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/entertainment/advice', {
  headers: {
    'requiems-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.advice);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/entertainment/advice')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['advice']
```

---
# Fitness Exercises

Browse 1,500+ exercises with step-by-step instructions, target muscles, secondary muscles, equipment requirements, and body part filters. Supports full-text search and pagination.

**Base URL:** `https://requiems.xyz`

## `GET /v1/health/exercises`

Returns a paginated list of exercises. All filter parameters are optional and combinable.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `body_part` | string | No | Filter by body part (e.g. chest, back, upper legs). Use /v1/health/body-parts for valid values. |
| `equipment` | string | No | Filter by equipment type (e.g. barbell, dumbbell, body weight). Use /v1/health/equipment for valid values. |
| `muscle` | string | No | Filter by target or secondary muscle (e.g. biceps, glutes). Use /v1/health/muscles for valid values. |
| `search` | string | No | Full-text search on exercise name. |
| `page` | integer | No | Page number (default: 1) |
| `per_page` | integer | No | Results per page, 1–100 (default: 20) |

### Response Example

```json
{
  "data": {
    "items": [
      {
        "id": 1,
        "name": "barbell bench press",
        "body_parts": ["chest"],
        "equipment": ["barbell"],
        "target_muscles": ["pectorals"],
        "secondary_muscles": ["triceps", "deltoids"],
        "instructions": [
          "Lie flat on a bench and grip the barbell slightly wider than shoulder-width.",
          "Lower the bar to your chest under control.",
          "Press the bar back up to full arm extension.",
          "Repeat for the desired number of repetitions."
        ]
      }
    ],
    "total": 312,
    "page": 1,
    "per_page": 20
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `items` | array<object> | Array of exercise objects for the current page |
| `items[].id` | integer | Unique exercise identifier |
| `items[].name` | string | Exercise name |
| `items[].body_parts` | array<string> | Body part categories involved |
| `items[].equipment` | array<string> | Equipment required |
| `items[].target_muscles` | array<string> | Primary muscles targeted |
| `items[].secondary_muscles` | array<string> | Secondary muscles engaged |
| `items[].instructions` | array<string> | Ordered step-by-step instructions |
| `total` | integer | Total number of exercises matching the filters |
| `page` | integer | Current page number |
| `per_page` | integer | Number of results per page |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | A query parameter has an invalid value (e.g. per_page out of range). |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/health/exercises?body_part=chest&equipment=barbell&per_page=10" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://requiems.xyz/v1/health/exercises"
headers = {"requiems-api-key": "YOUR_API_KEY"}
params = {"body_part": "chest", "equipment": "barbell", "per_page": 10}

response = requests.get(url, headers=headers, params=params)
data = response.json()
for exercise in data["data"]["items"]:
    print(exercise["name"])
```

**Javascript**

```javascript
const params = new URLSearchParams({ body_part: 'chest', equipment: 'barbell', per_page: 10 });
const response = await fetch(`https://requiems.xyz/v1/health/exercises?${params}`, {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
data.items.forEach(e => console.log(e.name));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/exercises')
uri.query = URI.encode_www_form(body_part: 'chest', equipment: 'barbell', per_page: 10)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
data = JSON.parse(response.body)
data['data']['items'].each { |e| puts e['name'] }
```

## `GET /v1/health/exercises/{id}`

Returns a single exercise by its numeric ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | Numeric exercise ID |

### Response Example

```json
{
  "data": {
    "id": 1,
    "name": "barbell bench press",
    "body_parts": ["chest"],
    "equipment": ["barbell"],
    "target_muscles": ["pectorals"],
    "secondary_muscles": ["triceps", "deltoids"],
    "instructions": [
      "Lie flat on a bench and grip the barbell slightly wider than shoulder-width.",
      "Lower the bar to your chest under control.",
      "Press the bar back up to full arm extension.",
      "Repeat for the desired number of repetitions."
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique exercise identifier |
| `name` | string | Exercise name |
| `body_parts` | array<string> | Body part categories involved |
| `equipment` | array<string> | Equipment required |
| `target_muscles` | array<string> | Primary muscles targeted |
| `secondary_muscles` | array<string> | Secondary muscles engaged |
| `instructions` | array<string> | Ordered step-by-step instructions |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The id parameter is not a positive integer. |
| `not_found` | 404 | No exercise exists with the given ID. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/health/exercises/1 \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://requiems.xyz/v1/health/exercises/1",
    headers={"requiems-api-key": "YOUR_API_KEY"}
)
print(response.json()["data"]["name"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/health/exercises/1', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
console.log(data.name);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/exercises/1')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']['name']
```

## `GET /v1/health/exercises/random`

Returns a single randomly selected exercise. Accepts the same filter parameters as the list endpoint, so you can get a random chest exercise, a random bodyweight exercise, etc.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `body_part` | string | No | Restrict random selection to this body part. |
| `equipment` | string | No | Restrict random selection to this equipment type. |
| `muscle` | string | No | Restrict random selection to exercises targeting this muscle. |
| `search` | string | No | Restrict random selection to exercises matching this search term. |

### Response Example

```json
{
  "data": {
    "id": 42,
    "name": "dumbbell curl",
    "body_parts": ["upper arms"],
    "equipment": ["dumbbell"],
    "target_muscles": ["biceps"],
    "secondary_muscles": ["brachialis"],
    "instructions": [
      "Stand with a dumbbell in each hand, arms fully extended.",
      "Curl the weights toward your shoulders, keeping your elbows close to your torso.",
      "Squeeze at the top, then lower the weights slowly.",
      "Repeat for the desired number of repetitions."
    ]
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `not_found` | 404 | No exercises match the given filters. |
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl "https://requiems.xyz/v1/health/exercises/random?body_part=back" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://requiems.xyz/v1/health/exercises/random",
    headers={"requiems-api-key": "YOUR_API_KEY"},
    params={"body_part": "back"}
)
print(response.json()["data"]["name"])
```

**Javascript**

```javascript
const response = await fetch(
  'https://requiems.xyz/v1/health/exercises/random?body_part=back',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(data.name, data.instructions);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/exercises/random')
uri.query = URI.encode_www_form(body_part: 'back')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']['name']
```

## `GET /v1/health/body-parts`

Returns a sorted list of all distinct body part values present in the dataset. Use these as valid values for the body_part filter.

### Response Example

```json
{
  "data": {
    "items": ["back", "cardio", "chest", "lower arms", "lower legs", "neck", "shoulders", "upper arms", "upper legs", "waist"],
    "total": 10
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `items` | array<string> | Sorted list of all distinct body part names |
| `total` | integer | Total number of distinct body parts |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/health/body-parts \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://requiems.xyz/v1/health/body-parts",
    headers={"requiems-api-key": "YOUR_API_KEY"}
)
print(response.json()["data"]["items"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/health/body-parts', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
console.log(data.items);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/body-parts')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']['items'].inspect
```

## `GET /v1/health/equipment`

Returns a sorted list of all distinct equipment types. Use these as valid values for the equipment filter.

### Response Example

```json
{
  "data": {
    "items": ["band", "barbell", "body weight", "cable", "dumbbell", "ez barbell", "kettlebell", "medicine ball", "stability ball", "tire"],
    "total": 28
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `items` | array<string> | Sorted list of all distinct equipment names |
| `total` | integer | Total number of distinct equipment types |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/health/equipment \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://requiems.xyz/v1/health/equipment",
    headers={"requiems-api-key": "YOUR_API_KEY"}
)
print(response.json()["data"]["items"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/health/equipment', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
console.log(data.items);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/equipment')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']['items'].inspect
```

## `GET /v1/health/muscles`

Returns a sorted list of all distinct muscle names (combining target and secondary muscles). Use these as valid values for the muscle filter.

### Response Example

```json
{
  "data": {
    "items": ["biceps", "calves", "deltoids", "glutes", "hamstrings", "lats", "pectorals", "quadriceps", "traps", "triceps"],
    "total": 51
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `items` | array<string> | Sorted list of all distinct muscle names |
| `total` | integer | Total number of distinct muscles |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `internal_error` | 500 | Unexpected server error. |

### Code Examples

**Curl**

```curl
curl https://requiems.xyz/v1/health/muscles \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://requiems.xyz/v1/health/muscles",
    headers={"requiems-api-key": "YOUR_API_KEY"}
)
print(response.json()["data"]["items"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/health/muscles', {
  headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
console.log(data.items);
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/muscles')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['data']['items'].inspect
```

## `POST /v1/health/exercises/batch`

Fetches up to 50 exercises by their numeric IDs in a single request. IDs that do not exist are silently skipped. Results are returned in the same order as the input array.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ids` | array<number> | Yes | Array of numeric exercise IDs to fetch. Must contain between 1 and 50 items. Each ID must be a positive integer. |

### Request

```json
{
  "ids": [1, 7, 42]
}
```

### Response Example

```json
{
  "data": {
    "results": [
      {
        "id": 1,
        "name": "barbell bench press",
        "body_parts": ["chest"],
        "equipment": ["barbell"],
        "target_muscles": ["pectorals"],
        "secondary_muscles": ["triceps", "deltoids"],
        "instructions": [
          "Lie flat on a bench and grip the barbell slightly wider than shoulder-width.",
          "Lower the bar to your chest under control.",
          "Press the bar back up to full arm extension.",
          "Repeat for the desired number of repetitions."
        ]
      },
      {
        "id": 7,
        "name": "dumbbell curl",
        "body_parts": ["upper arms"],
        "equipment": ["dumbbell"],
        "target_muscles": ["biceps"],
        "secondary_muscles": ["brachialis"],
        "instructions": [
          "Stand with a dumbbell in each hand, arms fully extended.",
          "Curl the weights toward your shoulders, keeping your elbows close to your torso.",
          "Squeeze at the top, then lower the weights slowly.",
          "Repeat for the desired number of repetitions."
        ]
      }
    ],
    "total": 2
  },
  "metadata": {
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `results` | array<object> | Exercises found for the given IDs, in input order. IDs not found are omitted. |
| `results[].id` | integer | Unique exercise identifier |
| `results[].name` | string | Exercise name |
| `results[].body_parts` | array<string> | Body part categories involved |
| `results[].equipment` | array<string> | Equipment required |
| `results[].target_muscles` | array<string> | Primary muscles targeted |
| `results[].secondary_muscles` | array<string> | Secondary muscles engaged |
| `results[].instructions` | array<string> | Ordered step-by-step instructions |
| `total` | integer | Number of exercises returned |

### Errors

| Code | Status | Description |
|------|--------|-------------|
| `bad_request` | 400 | The request body is missing or not valid JSON. |
| `validation_failed` | 422 | The ids array is empty, exceeds 50 items, or contains a non-positive integer. |

### Code Examples

**Curl**

```curl
curl -X POST https://requiems.xyz/v1/health/exercises/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 7, 42]}'
```

**Python**

```python
import requests

response = requests.post(
    "https://requiems.xyz/v1/health/exercises/batch",
    headers={"requiems-api-key": "YOUR_API_KEY"},
    json={"ids": [1, 7, 42]}
)
for exercise in response.json()["data"]["results"]:
    print(exercise["name"])
```

**Javascript**

```javascript
const response = await fetch('https://requiems.xyz/v1/health/exercises/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ids: [1, 7, 42] })
});
const { data } = await response.json();
data.results.forEach(e => console.log(e.name));
```

**Ruby**

```ruby
require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/health/exercises/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { ids: [1, 7, 42] }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
JSON.parse(response.body)['data']['results'].each { |e| puts e['name'] }
```

---