API Reference

Base URL

https://api.mockhero.dev/api/v1

POST /generate Core

The primary endpoint. Accepts one of three mutually exclusive input modes: schema, prompt, or template. Returns generated data in your chosen format.

Common Parameters

Schema Mode

Pass a tables array with explicit field definitions for full control.

Request

POST /api/v1/generate
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "tables": [
    {
      "name": "products",
      "count": 3,
      "fields": [
        { "name": "id",    "type": "uuid" },
        { "name": "title", "type": "product_name" },
        { "name": "price", "type": "price", "params": { "min": 9.99, "max": 299.99 } },
        { "name": "sku",   "type": "sku" },
        { "name": "active","type": "boolean" }
      ]
    }
  ],
  "format": "json"
}

Response

{
  "data": {
    "products": [
      { "id": "d4e5f6a7-...", "title": "Ergonomic Mesh Chair", "price": 189.50, "sku": "SKU-8A3F2C", "active": true },
      { "id": "b1c2d3e4-...", "title": "Wireless Noise-Canceling Headphones", "price": 74.99, "sku": "SKU-1D7E9B", "active": true },
      { "id": "f8a9b0c1-...", "title": "USB-C Docking Station", "price": 129.00, "sku": "SKU-4G6H2K", "active": false }
    ]
  },
  "meta": {
    "tables": 1,
    "total_records": 3,
    "records_per_table": { "products": 3 },
    "format": "json",
    "locale": "en",
    "seed": 4419827,
    "generation_time_ms": 89
  }
}

Prompt Mode

Describe the data you need in plain English. MockHero infers the schema, generates the data, and returns the inferred schema alongside the results.

Request

POST /api/v1/generate
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "prompt": "A blog platform with 5 authors and 12 posts. Each post has a title, slug, markdown body, published date, and belongs to one author.",
  "format": "json"
}

Response

{
  "data": {
    "authors": [
      { "id": "a1b2c3d4-...", "name": "Priya Sharma", "email": "priya.sharma@example.com" }
    ],
    "posts": [
      {
        "id": "e5f6a7b8-...",
        "author_id": "a1b2c3d4-...",
        "title": "Understanding Event-Driven Architecture",
        "slug": "understanding-event-driven-architecture",
        "body": "## Introduction\n\nEvent-driven architecture...",
        "published_at": "2025-11-03T09:14:00Z"
      }
    ]
  },
  "meta": {
    "tables": 2,
    "total_records": 17,
    "records_per_table": { "authors": 5, "posts": 12 },
    "format": "json",
    "locale": "en",
    "seed": 7723041,
    "generation_time_ms": 312
  }
}

Template Mode

Use a pre-built template for common data shapes. See Templates for full details on each template.

Request

POST /api/v1/generate
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "template": "saas",
  "scale": 2,
  "format": "json"
}

GET /types

Returns the full list of supported field types, grouped by category, including accepted parameters for each type.

Request

GET /api/v1/types

Response (truncated)

{
  "identity": {
    "first_name": {
      "description": "Locale-aware first name",
      "params": {},
      "example": "Amara"
    },
    "email": {
      "description": "Realistic email address based on name fields",
      "params": { "domain": "string (optional, e.g. 'company.de')" },
      "example": "amara.okafor@gmail.com"
    }
  },
  "location": { "...": "..." },
  "financial": { "...": "..." },
  "locales": ["en", "de", "fr", "..."],
  "formats": ["json", "csv", "sql"]
}

GET /templates

Lists all available templates with their default table counts and descriptions.

Request

GET /api/v1/templates

Response

{
  "templates": [
    {
      "id": "ecommerce",
      "name": "E-Commerce",
      "description": "Storefront with customers, products, orders, line items, and reviews.",
      "tables": ["customers", "products", "orders", "order_items", "reviews"],
      "default_counts": { "customers": 100, "products": 50, "orders": 300, "order_items": 900, "reviews": 200 }
    },
    {
      "id": "blog",
      "name": "Blog",
      "description": "Multi-author blog with posts, comments, tags, and a post_tags junction table.",
      "tables": ["authors", "posts", "comments", "tags", "post_tags"],
      "default_counts": { "authors": 30, "posts": 150, "comments": 600, "tags": 20, "post_tags": 400 }
    },
    {
      "id": "saas",
      "name": "SaaS",
      "description": "Multi-tenant SaaS with organizations, members, subscriptions, and invoices.",
      "tables": ["organizations", "members", "subscriptions", "invoices"],
      "default_counts": { "organizations": 20, "members": 100, "subscriptions": 20, "invoices": 120 }
    },
    {
      "id": "social",
      "name": "Social Network",
      "description": "Social platform with users, posts, likes, follows, and direct messages.",
      "tables": ["users", "posts", "likes", "follows", "messages"],
      "default_counts": { "users": 150, "posts": 600, "likes": 3000, "follows": 2000, "messages": 1000 }
    }
  ]
}

POST /schema/detect Pro+

Upload a SQL CREATE TABLE statement or JSON sample and MockHero will detect the schema and return a ready-to-use table definition you can pass directly to the generate endpoint.

Request

POST /api/v1/schema/detect
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "sql": "CREATE TABLE users (\n  id UUID PRIMARY KEY,\n  name VARCHAR(100),\n  email VARCHAR(255) UNIQUE,\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);"
}

Response

{
  "schema": {
    "tables": [
      {
        "name": "users",
        "fields": [
          { "name": "id",         "type": "uuid" },
          { "name": "name",       "type": "full_name" },
          { "name": "email",      "type": "email" },
          { "name": "created_at", "type": "timestamp" }
        ]
      }
    ]
  }
}

POST /generate/async Scale

Asynchronous bulk generation for large datasets. Creates a job and returns a 202 immediately. Poll the job status endpoint to retrieve results when complete. Supports the same three input modes as the sync endpoint (schema, prompt, template).

Request

POST /api/v1/generate/async
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "template": "ecommerce",
  "scale": 10,
  "format": "json"
}

Response (202 Accepted)

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "poll_url": "/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "records_total": 15500
}

Limits

GET /jobs/:id Scale

Poll the status of an async job. Returns the generated data in the data field once the job completes.

Request

GET /api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

Response (completed)

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "records_total": 15500,
  "created_at": "2026-03-20T14:30:00Z",
  "started_at": "2026-03-20T14:30:00Z",
  "completed_at": "2026-03-20T14:30:12Z",
  "data": { "customers": [...], "orders": [...] }
}

Job Statuses

Webhooks Scale

Receive HTTP POST notifications when generation completes. Useful for async workflows and CI/CD pipelines. Each webhook delivery includes an HMAC-SHA256 signature for verification.

POST /webhooks

Register a webhook endpoint. The secret is returned only once — store it securely.

Request

POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

{
  "url": "https://your-app.com/api/mockhero-webhook",
  "events": ["generation.completed"]
}

Response

{
  "id": "a1b2c3d4-...",
  "url": "https://your-app.com/api/mockhero-webhook",
  "events": ["generation.completed"],
  "secret": "e8f3a9b1c7d2e5f4a6b8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1"
}

GET /webhooks

List all active webhooks. Secrets are not returned in the list response.

DELETE /webhooks/:id

Remove a webhook. It will no longer receive deliveries.

Webhook Payload

Each delivery is a POST to your URL with these headers:

Verifying Signatures

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

GET /health

Public endpoint (no auth required) that returns API status. Useful for uptime monitoring.

Request

GET /api/v1/health

Response

{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2026-03-20T14:30:00Z"
}

Response Headers

Every authenticated response includes rate-limit headers so you can track usage programmatically.

Error Codes

See the full Error Codes page for detailed examples. Here is a summary.

All error responses follow a consistent envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong."
  }
}