BugiaData Documentation

Overview

BugiaData is a Fake Data as a Service (FDaaS) API that generates locale-specific fake data using the Faker library. All protected endpoints require an API key in the X-API-Key header. You get your API key after subscribing to a tier (FREE, STARTER, or PRO) via checkout.

Quick start

1. Get your API key from the success page after checkout or from your dashboard.
2. Send POST /api/generate with the X-API-Key header and a JSON body.

Example request:

curl -X POST https://your-api-host/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"type": "name", "count": 5}'

Technical specifications

Headers

All protected endpoints require:

• X-API-Key (required): Your API key. Format: sk_fd_{tier}_{random}. Obtain it after subscription or from the dashboard.

Query parameters

The main data endpoints (/api/generate, /api/usage) do not use query parameters. All input is in the request body (for POST) or none (for GET).

Path parameters

The consumer data endpoints have no path parameters: /api/generate, /api/usage, /api/rotate-key.

Locale-Specific API

Pass the locale parameter in the request body to get locale-specific data (e.g. en_US, ja_JP, fr_FR). Over 100 locales are supported.

Request body (POST /api/generate)

Send JSON with:

• type (required): Faker data type, e.g. name, email, address.
• count (optional, default 1): Number of items to generate, between 1 and 100. Token-based billing: 1 token = 1 generated element (e.g., count=100 charges 100 tokens).
• locale (optional): Locale code for locale-specific data. This is a body parameter, not a query parameter. Examples: en_US, ja_JP, fr_FR, de_DE. Supports 100+ locales.

For multi-table relational data in one request, see Custom schema & relational data seeding below.

Custom schema & relational data seeding

Relational Fake Data

Use POST /api/generate/schema to generate multi-table relational data in a single request. You send a JSON schema defining tables and columns; columns can use Faker types or foreign_key with a reference to another table’s column. The API resolves dependency order (parent tables first) and returns a consistent dataset.

When to use it

Seeding test databases, generating users + posts + comments, or any multi-table scenario without multiple round-trips.

Request body

• count (required): Number of rows per table, between 1 and 100.
• schema (required): Object mapping table names to { "columns": { "colName": { "type", optional "locale", optional "reference" } } }.
• locale (optional): Default locale for Faker (e.g. en_US). Can also be set per column.

Column type accepts any valid Faker provider method name (e.g. name, email, uuid, random_number, sentence, paragraph, date, company). The name uuid is aliased to Faker’s uuid4. For relational references use foreign_key with reference: "table.column".

Dependency order

Parent tables are generated first; foreign keys reference already-generated values. Circular dependencies or invalid references return 400 with a descriptive message.

Token billing

tokens_to_charge = (total columns across all tables) × count. The limit is checked before execution; if insufficient, the API returns 402.

Example request

{
  "count": 10,
  "schema": {
    "users": {
      "columns": {
        "id": {"type": "uuid"},
        "name": {"type": "name", "locale": "en_US"},
        "email": {"type": "email"}
      }
    },
    "posts": {
      "columns": {
        "id": {"type": "uuid"},
        "author_id": {"type": "foreign_key", "reference": "users.id"},
        "title": {"type": "sentence"},
        "content": {"type": "paragraph"}
      }
    }
  }
}

Example with curl:

curl -X POST https://your-api-host/api/generate/schema \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"count": 5, "schema": {"users": {"columns": {"id": {"type": "uuid"}, "name": {"type": "name"}}}, "posts": {"columns": {"id": {"type": "uuid"}, "author_id": {"type": "foreign_key", "reference": "users.id"}}}}}'

Example response (200)

{
  "data": {
    "users": [
      {"id": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", "email": "[email protected]"},
      ...
    ],
    "posts": [
      {"id": "a1b2c3d4-...", "author_id": "550e8400-e29b-41d4-a716-446655440000", "title": "A title.", "content": "..."},
      ...
    ]
  }
}

Errors

• 400: Invalid schema, missing/invalid count, circular dependency, or invalid reference.
• 402: Token limit would be exceeded.

Endpoints summary

Request flow

Send the X-API-Key header with every request to protected endpoints.

Client  --[X-API-Key + JSON body]-->  POST /api/generate  -->  {"data": [...]}
Client  --[X-API-Key]----------------->  GET /api/usage    -->  {"tier", "usage_count", "remaining_tokens", ...}

Example JSON responses

POST /api/generate (200)

{
  "data": [
    "John Doe",
    "Jane Smith",
    "Bob Johnson",
    "Alice Williams",
    "Charlie Brown"
  ]
}

GET /api/usage (200)

{
  "api_key_prefix": "sk_fd_free_...",
  "tier": "FREE",
  "usage_count": 42,
  "max_monthly_tokens": 10000,
  "remaining_tokens": 9958,
  "subscription_active": true
}

Frequently Asked Questions

Interactive documentation with try-it-out for all endpoints.