API Documentation

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
  }
]

Apiryner supports two authentication methods:

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

# Login via OAuth PKCE (opens the browser)
npx apiryner login

# Use token
curl -H "Authorization: Bearer oat_your_token" \
  -X POST https://api.apiryner.com/v1/layouts \
  -H "Content-Type: application/json" \
  -d '{"name": "Users", "slug": "users", "schema": {"id": {"type": "uuid"}}}'

Conditional fields

Any field can carry a condition that decides per record whether the field is included, based on a previously generated field in the same record:

{
  "status": { "type": "enum", "options": { "values": ["active", "banned"] } },
  "banned_reason": {
    "type": "sentence",
    "condition": { "field": "status", "equals": "banned" }
  }
}

When the condition doesn't match, the field is omitted from that record. The condition's field must name a field in the same object.

Snapshots

A snapshot freezes one generated dataset so every call returns the same bytes — for demos, screenshots and fixtures that must not move under you.

curl -X POST https://api.apiryner.com/v1/snapshots \
  -H "Authorization: Bearer oat_your_token" \
  -H "Content-Type: application/json" \
  -d '{"layout_slug": "users", "name": "Demo users",
       "slug": "demo-users", "count": 20, "seed": 42}'

• GET /v1/snapshots/:slug serves the stored data, and ?format=csv works as it does on a layout.
• shape — auto (default), object or array — decides whether the snapshot answers with a single object or an array. Auto follows the layout.
• PUT /v1/snapshots/:slug replaces name or data, so pinned records can be hand-edited.
• Serving a snapshot still counts against your monthly record quota — pinned data is data the API delivers.

Delivery & verification

Each delivery is a JSON POST carrying two headers: X-Apiryner-Event with the event name, and X-Apiryner-Signature with an HMAC-SHA256 of the raw request body, keyed with your secret and hex-encoded. Verify it before trusting the payload:

const expected = crypto
  .createHmac("sha256", secret)
  .update(rawBody)          // the raw body, before JSON.parse
  .digest("hex");

if (expected !== req.headers["x-apiryner-signature"]) {
  return res.status(401).end();
}

Delivery times out after 10 seconds. Network errors and 408/429/5xx responses are retried twice — after 5 and 30 seconds — while any other 4xx is final. Every attempt is recorded; read them back with GET /v1/webhooks/:id/deliveries.

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
    }
  }
}

Every pool-backed type — name, email, phone, the address types, the text types and slug — also accepts a locale option that overrides the request’s locale for that one field. A field that overrides the locale generates its own identity rather than sharing the record’s person:

{
  "name": {"type": "name"},
  "korean_name": {"type": "name", "options": {"locale": "ko"}}
}

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"]
    }
  }
}

Rate limits & quota

Every response carries the per-minute budget:

• X-RateLimit-Limit — requests allowed per minute on your plan
• X-RateLimit-Remaining — how many are left in the current window
• X-RateLimit-Reset — when the window resets, as a Unix timestamp
• Retry-After — seconds to wait, sent only with a 429

Monthly quota is counted in two dimensions, requests and records; a bundle call counts as one request plus every record it returns. Read the current period with GET /v1/account/usage:

{
  "requests": 128,
  "records": 4210,
  "limit_requests": 1000,
  "limit_records": 10000,
  "period": "2026-08"
}

A count above your plan’s per-request maximum is capped rather than rejected, so a request never fails for asking too much. Layout, API key and nesting-depth limits are enforced the same way, at the point of use.

Authentication

validate_schema, infer_schema, and quick_generate run entirely on your machine — no account, no network. An agent can build fixtures or turn an OpenAPI file into a layout schema before you have signed up.

list_types is what keeps an agent from inventing field types. Authenticated, it returns this page’s full type catalog with descriptions and supported locales; unauthenticated, it falls back to the type names built into the package rather than failing.

The remote server authorizes through your browser: your agent registers itself, you approve it once, and the token it receives is bound to this endpoint alone. An X-API-Key header works too, and keeps the read-only limits an API key always has.

For the local server, credentials are resolved on the first tool call that needs the API, in this order:

1. --key <key> passed after apiryner mcp, or $APIRYNER_API_KEY
2. the OAuth session from apiryner login, refreshed automatically when expired
3. the API key stored by apiryner config set api-key <key>

Starting the server unauthenticated is fine: the account-backed tools explain what is missing and begin working the moment you log in, with no restart. Note that create_layout, update_layout and delete_layout write to your account, and that a delete cannot be undone.