# 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://api.requiems.xyz`
**Authentication:** `requiems-api-key` header

---
# 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://api.requiems.xyz`

## `POST /v1/email/validate`

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|null | 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|null | The canonical form of the address after normalization (lowercase, plus-tag removal, alias-domain resolution). Null when syntax is invalid |
| `domain` | string|null | 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://api.requiems.xyz/v1/email/validate \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@gmial.com"}'
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/email/validate"
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://api.requiems.xyz/v1/email/validate', {
  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://api.requiems.xyz/v1/email/validate')
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
```

---
# 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://api.requiems.xyz`

## `POST /v1/email/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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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/email/disposable/check-batch`

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

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array | 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 | 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://api.requiems.xyz/v1/email/disposable/check-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://api.requiems.xyz/v1/email/disposable/check-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://api.requiems.xyz/v1/email/disposable/check-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/email/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://api.requiems.xyz/v1/email/disposable/domain/tempmail.com \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

domain = "tempmail.com"
url = f"https://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/disposable/domain/${domain}`,
  {
    headers: {
      'requiems-api-key': 'YOUR_API_KEY'
    }
  }
);

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

## `GET /v1/email/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://api.requiems.xyz/v1/email/disposable/stats \
  -H "requiems-api-key: YOUR_API_KEY"
```

## `GET /v1/email/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 | 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://api.requiems.xyz/v1/email/disposable/domains?page=1&per_page=100" \
  -H "requiems-api-key: YOUR_API_KEY"
```

---
# 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://api.requiems.xyz`

## `POST /v1/email/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 | 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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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://api.requiems.xyz/v1/email/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
```

---
# 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://api.requiems.xyz`

## `GET /v1/tech/validate/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://api.requiems.xyz/v1/tech/validate/phone?number=%2B447400123456" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/validate/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://api.requiems.xyz/v1/tech/validate/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://api.requiems.xyz/v1/tech/validate/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/tech/validate/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 | 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 | 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://api.requiems.xyz/v1/tech/validate/phone/batch" \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+447400123456","+12015551234"]}'
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/validate/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://api.requiems.xyz/v1/tech/validate/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://api.requiems.xyz/v1/tech/validate/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://api.requiems.xyz`

## `POST /v1/text/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 of strings | 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://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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']
```

---
# 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://api.requiems.xyz`

## `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", "position": 0},
      {"original": "smiple", "suggested": "simple", "position": 9},
      {"original": "tset", "suggested": "test", "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 their suggested corrections |
| `corrections` | array of objects | List of individual corrections. Each item contains: original (the misspelled word), suggested (the correction), and position (0-based 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://api.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://api.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://api.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://api.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']}" }
```

---
# Thesaurus

Find synonyms and antonyms for any word. Perfect for vocabulary building, writing assistance, and educational applications.

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

## `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 of strings | List of words with similar meaning |
| `antonyms` | array of strings | 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://api.requiems.xyz/v1/text/thesaurus/happy \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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://api.requiems.xyz`

## `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": [
      {
        "partOfSpeech": "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 of objects | One or more definitions for the word, each with partOfSpeech, definition, and an optional example |
| `definitions[].partOfSpeech` | 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 of strings | 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://api.requiems.xyz/v1/text/dictionary/ephemeral \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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['partOfSpeech']}] {d['definition']}")
    if d.get('example'):
        print(f"  Example: {d['example']}")
print(f"Synonyms: {', '.join(data['synonyms'])}")
```

**Javascript**

```javascript
const response = await fetch('https://api.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.partOfSpeech}] ${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://api.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['partOfSpeech']}] #{d['definition']}"
  puts "  Example: #{d['example']}" if d['example']
end
puts "Synonyms: #{data['synonyms'].join(', ')}"
```

---
# 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://api.requiems.xyz`

## `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,
    "wordCount": 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 |
| `wordCount` | 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://api.requiems.xyz/v1/text/lorem?paragraphs=3&sentences=5" \
  -H "requiems-api-key: YOUR_API_KEY"

# Generate 1 paragraph with 10 sentences
curl "https://api.requiems.xyz/v1/text/lorem?sentences=10" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# 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://api.requiems.xyz`

## `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://api.requiems.xyz/v1/text/words/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']}"
```

---
# Password Generator

Generate cryptographically secure random passwords with customizable complexity. Perfect for user registration, password reset flows, or security tools.

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

## `GET /v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/password?length=12" \
  -H "requiems-api-key: YOUR_API_KEY"

# Generate 20-character alphanumeric password
curl "https://api.requiems.xyz/v1/tech/password?length=20&uppercase=true&numbers=true" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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']}"
```

---
# User Agent Parser

Parse user agent strings to extract browser name, version, operating system, device type, and bot detection.

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

## `GET /v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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']
```

---
# Counter

Atomic, namespace-isolated hit counter. Perfect for tracking page views, downloads, or any event that needs counting.

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

## `POST /v1/misc/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://api.requiems.xyz/v1/misc/counter/page-views \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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/misc/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://api.requiems.xyz/v1/misc/counter/page-views \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz`

## `GET /v1/misc/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://api.requiems.xyz/v1/misc/random-user \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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']}>"
```

---
# Base64 Encode / Decode

Encode strings to Base64 and decode Base64 back to plain text. Supports standard and URL-safe (base64url) variants.

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

## `POST /v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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/convert/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://api.requiems.xyz/v1/convert/base64/decode \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "SGVsbG8sIHdvcmxkIQ=="}'

# URL-safe variant
curl -X POST https://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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
```

---
# 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://api.requiems.xyz`

## `GET /v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/qr?data=https://example.com" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output qrcode.png
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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/tech/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://api.requiems.xyz/v1/tech/qr/base64?data=https://example.com&size=200&recovery=highest" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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] + '...'
```

---
# 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://api.requiems.xyz`

## `GET /v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/barcode?data=123456789012&type=ean13" \
  -H "requiems-api-key: YOUR_API_KEY" \
  --output barcode.png
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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/tech/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://api.requiems.xyz/v1/tech/barcode/base64?data=123456789&type=code128" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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://api.requiems.xyz/v1/tech/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] + '...'
```

---
# 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://api.requiems.xyz`

## `POST /v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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)})"
```

---
# Language Detection

Detect the language of any text and receive the language name, ISO 639-1 code, and a confidence score.

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

## `POST /v1/ai/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` | float | 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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz`

## `POST /v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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://api.requiems.xyz/v1/ai/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']
```

---
# 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://api.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` | float | No | Latitude of the location (-90 to 90). Required when using coordinate-based lookup. |
| `lon` | float | 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://api.requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1" \
  -H "requiems-api-key: YOUR_API_KEY"

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

**Python**

```python
import requests

# Lookup by coordinates
url = "https://api.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://api.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://api.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://api.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']
```

---
# 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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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 | 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://api.requiems.xyz/v1/places/holidays?country=US&year=2025" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# 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://api.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://api.requiems.xyz/v1/places/time/America/New_York" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# 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://api.requiems.xyz`

## `GET /v1/text/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://api.requiems.xyz/v1/text/quotes/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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']}"
```

---
# Random Advice

Get random pieces of advice and wisdom for inspiration, daily motivation, or content generation.

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

## `GET /v1/text/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://api.requiems.xyz/v1/text/advice \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

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

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

**Javascript**

```javascript
const response = await fetch('https://api.requiems.xyz/v1/text/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://api.requiems.xyz/v1/text/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']
```

---
# Horoscope

Get daily horoscope readings for all 12 zodiac signs. Each reading is deterministically generated per sign per day.

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

## `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://api.requiems.xyz/v1/entertainment/horoscope/aries \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# 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://api.requiems.xyz`

## `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[array[integer]] | 9×9 grid representing the puzzle — 0 means an empty cell to be filled in |
| `solution` | array[array[integer]] | 9×9 grid containing the 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://api.requiems.xyz/v1/entertainment/sudoku?difficulty=hard" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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
```

---
# 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://api.requiems.xyz`

## `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://api.requiems.xyz/v1/entertainment/emoji/random \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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 | 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://api.requiems.xyz/v1/entertainment/emoji/search?q=happy" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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://api.requiems.xyz/v1/entertainment/emoji/grinning_face \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# Trivia

Get random trivia questions with multiple-choice answers. Filter by category and difficulty to target specific question pools.

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

## `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://api.requiems.xyz/v1/entertainment/trivia" \
  -H "requiems-api-key: YOUR_API_KEY"

# Filtered by category and difficulty
curl "https://api.requiems.xyz/v1/entertainment/trivia?category=science&difficulty=medium" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']}"
```

---
# 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://api.requiems.xyz`

## `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://api.requiems.xyz/v1/entertainment/chuck-norris \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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 Facts

Get random interesting facts from a curated database covering science, history, technology, nature, space, and food.

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

## `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://api.requiems.xyz/v1/entertainment/facts \
  -H "requiems-api-key: YOUR_API_KEY"

# Random science fact
curl "https://api.requiems.xyz/v1/entertainment/facts?category=science" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']}"
```

---
# Dad Jokes

Get a random dad joke. Classic groan-worthy puns and wholesome humor, served one at a time.

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

## `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://api.requiems.xyz/v1/entertainment/jokes/dad \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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']
```

---
# 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://api.requiems.xyz`

## `POST /v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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://api.requiems.xyz/v1/convert/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']
```

---
# Unit Conversion

Convert between units of measurement and discover available conversion types. Supports length, weight, volume, temperature, area, and speed conversions.

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

## `GET /v1/misc/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://api.requiems.xyz/v1/misc/convert?from=miles&to=km&value=10" \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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/misc/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 | Available length units: millimeter (mm), centimeter (cm), meter (m), kilometer (km), inch (in), foot (ft), yard (yd), mile (miles), nautical mile (nmi) |
| `weight` | array | Available weight units: milligram (mg), gram (g), kilogram (kg), metric ton (t), ounce (oz), pound (lb), stone (stone) |
| `volume` | array | 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 | Available temperature units: celsius (c), fahrenheit (f), kelvin (k) |
| `area` | array | 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 | 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://api.requiems.xyz/v1/misc/convert/units \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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://api.requiems.xyz/v1/misc/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(', ')}"
```

---
# BIN Lookup

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

**Base URL:** `https://api.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": 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` | boolean | Whether the BIN prefix passes the Luhn algorithm check |
| `confidence` | number | Data quality score (0.00–1.00). Multi-source confirmed records score higher. |

### 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://api.requiems.xyz/v1/finance/bin/424242 \
  -H "requiems-api-key: YOUR_API_KEY"
```

**Python**

```python
import requests

url = "https://api.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://api.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://api.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"
```

---