API Documentation

Everything you need to generate realistic mock data with the Apiryner API.

Quick Start

Generate random data in 3 steps:

  1. Create a Layout — define your data schema with field names and types
  2. Get an API Key — create one from the API Keys page
  3. Make a Request — call the API with your layout slug

Example request:

curl -H "X-API-Key: ak_your_key_here" \
  "https://api.apiryner.com/v1/layouts/user-profile?count=2&locale=en"

Example response:

[
  {
    "id": 1,
    "name": "Sarah Johnson",
    "email": "[email protected]",
    "age": 28,
    "is_active": true
  },
  {
    "id": 2,
    "name": "James Wilson",
    "email": "[email protected]",
    "age": 45,
    "is_active": true
  }
]

Authentication

Apiryner supports two authentication methods:

API Key (Read-Only)

Pass your API key in the X-API-Key header. API keys can only read/generate data.

curl -H "X-API-Key: ak_your_key_here" \
  https://api.apiryner.com/v1/layouts/my-layout

Bearer Token (Full Access)

Use a Bearer token for full CRUD access. Obtain a token by logging in via POST /v1/auth/login.

# Login to get token
curl -X POST https://api.apiryner.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your_password"}'

# Use token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.apiryner.com/v1/layouts

Endpoints

Method Endpoint Auth Description
GET /v1/layouts/:slug API Key / Bearer Generate data from a layout
GET /v1/layouts Bearer List your layouts
POST /v1/layouts Bearer Create a layout
PUT /v1/layouts/:slug Bearer Update a layout
DELETE /v1/layouts/:slug Bearer Delete a layout
GET /v1/api-keys Bearer List your API keys
POST /v1/api-keys Bearer Create an API key
GET /v1/templates None List preset templates

Query Parameters for Data Generation

When calling GET /v1/layouts/:slug:

Parameter Type Default Description
count integer 10 Number of records to generate (max depends on plan)
locale string en Data locale (en, ko)
seed integer random Seed for reproducible data. Same seed = same output
format string json Response format (json, csv)

Data Types

Apiryner supports 30+ data types organized by category. Use the type field in your schema to specify each field's generator.

Basic

Type Description Options
integer Random integer within a range min, max
decimal Random decimal number min, max, precision
boolean Random true/false value true_rate
string Random string of characters length, charset
enum Pick from a list of values values

Nested

Type Description Options
object Nested JSON object properties (nested schema)
array Array of items items, min_items, max_items

Personal

Type Description Options
name Full person name gender
email Email address domain
phone Phone number format
address Full address —
city City name —
zipcode Postal/ZIP code —
street Street name with number —

Text

Type Description Options
word Random word —
sentence Random sentence words
paragraph Random paragraph sentences
description Descriptive text length (short/medium/long)

Date & Time

Type Description Options
date Random date from, to, format
datetime Random date and time from, to
time Random time format

Finance

Type Description Options
currency Random monetary amount currency, min, max
price Product price currency, min, max

Identifiers

Type Description Options
uuid UUID v4 —
slug URL-friendly slug words
sequence Auto-incrementing number start, prefix

Media

Type Description Options
image_url Random image URL (placeholder) width, height
color Random color code format (hex/rgb/rgba)

Options Reference

Each field in a schema can have a type and optional options object.

Schema field structure:

{
  "field_name": {
    "type": "integer",
    "options": {
      "min": 1,
      "max": 100
    }
  }
}

Nested object example:

{
  "address": {
    "type": "object",
    "properties": {
      "street": {"type": "street"},
      "city": {"type": "city"},
      "zipcode": {"type": "zipcode"}
    }
  }
}

Array example:

{
  "tags": {
    "type": "array",
    "items": {"type": "word"},
    "options": {"min_items": 2, "max_items": 5}
  }
}

Enum example:

{
  "status": {
    "type": "enum",
    "options": {
      "values": ["active", "inactive", "pending"]
    }
  }
}