API docs

Generate random data over HTTP. All methods below use GET and return JSON.

How to use the API

GET /api/v1/*

The external API is available to registered users with a verified email. Every endpoint, including catalogs, requires a user Bearer token. Up to 100 results per run. Technical safety limits remain: up to 10,000 results per request, up to 20,000 field values in the builder, natural generator limits and external provider quotas. Standard API: 60 requests/minute.

Register, verify your email and sign in. Open Account → API token → Show token and copy it. Account ↗
Send the token only in the Authorization: Bearer TOKEN header. Replace TOKEN with your value, without quotes around it. A public Supabase key cannot be used here.
Choose an endpoint below, copy its URL and use the parameters in its table. The examples use the integer generator; change the path and parameters for other generators.

This is a temporary Supabase session access token, not a permanent API key. Its lifetime is set in the project settings. On 401, reopen Account, sign in if needed and copy a current token. A static token in a script does not refresh itself. Keep it secret: it grants your session permissions.

Request

Requests: GET over HTTPS, with query string parameters and no JSON body. Encode values with URLSearchParams or your library equivalent; use one value per parameter. count is a positive integer, usually up to 10000; see each endpoint for exact limits and values. Opening a link without the token header returns 401.

GET https://rand.by/api/v1/integer?count=3&min=1&max=100
Authorization: Bearer TOKEN

Response

Success: HTTP 200 and JSON containing an items array. Item types depend on the generator. Catalogs have separate shapes: money/currencies returns asOf and items; geo/catalog returns a catalog object. Responses are not cached. Check HTTP status before parsing JSON; the numbers shown are illustrative.

{ "items": [42, 7, 91] }

Ready-to-run examples and setup

For server examples, set RANDBY_API_TOKEN in the process environment; the curl tab shows export and PowerShell shows the Windows version. Then follow the selected setup. Keep secrets out of Git, URLs, logs and public Nuxt variables. In browsers, use only the current user’s token; keep shared tokens on the server. The Nuxt route example needs your own authentication and rate limits, otherwise its proxy exposes access using your token.

Setup

export RANDBY_API_TOKEN='PASTE_TOKEN_HERE'

curl

curl --fail-with-body --max-time 15 --get 'https://rand.by/api/v1/integer' \
  --header "Authorization: Bearer $RANDBY_API_TOKEN" \
  --data-urlencode 'count=3' \
  --data-urlencode 'min=1' \
  --data-urlencode 'max=100'

Errors and next steps
400	Invalid parameters, repeated values or a technical limit exceeded. Check the endpoint table and correct the request.
401	Missing, invalid or expired token; also check email verification. Obtain a current token in Account and retry.
404	Unknown path or generator. Check the URL; API paths do not use a language prefix such as /en.
429	Public demo rate exceeded. Wait a minute and avoid retrying in a loop without a delay.
503	The authentication service is unavailable or not configured. Retry later; service owners should check the Supabase configuration.

The sandbox below works without a token through a separate demo route: up to 10 records and 60 requests per minute per IP. The external /api/v1/* remains private and uses endpoint technical limits.

Seeded generation for CI

POSTPremium

The same schema and seed produce the same test data with the same generation version and data catalogs.

CI API keys · Create a key and store it as the CI secret RANDBY_CI_KEY.
Export schema · Export your Builder schema as JSON and keep it with your test fixtures.
Choose an example below and run it from the directory containing your exported schema.

Use a Premium CI key in the Authorization header. Keep it in your CI secret store. Each key expires after 90 days. To rotate it, create a replacement, update the secret, and revoke the old key after a successful run.

Request

Send a POST request with Content-Type application/json. The JSON body has three fields.

schema: Required JSON object. Use the contents of the exported Builder schema, including any linked tables.
seed: Required nonblank string of up to 128 characters. Keep it fixed for repeatable runs and change it to sample a different dataset.
version: Optional engine version. The current value and default are v1. Set it explicitly in CI.

POST https://rand.by/api/builder/ci/generate
Authorization: Bearer CI_KEY
Content-Type: application/json

{
  "schema": {
    "version": 1,
    "count": 2,
    "fields": [
      {
        "id": "id",
        "path": "id",
        "generator": "sequence",
        "output": "value",
        "settings": {
          "start": 1,
          "step": 1
        },
        "array": false,
        "size": 1,
        "nullPercent": 0
      }
    ]
  },
  "seed": "fixtures-v1",
  "version": "v1"
}

Response

The response includes version and either items and columns, or tables for a multi-table schema. Keep the schema and seed fixed to repeat a run.

Single table

{
  "version": "v1",
  "columns": [
    "id"
  ],
  "items": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}

Multiple tables

{
  "version": "v1",
  "tables": [
    {
      "id": "main",
      "name": "users",
      "columns": [
        "id"
      ],
      "items": [
        {
          "id": 1
        }
      ]
    },
    {
      "id": "orders",
      "name": "orders",
      "columns": [
        "user_id"
      ],
      "items": [
        {
          "user_id": 1
        }
      ]
    }
  ]
}

Keep the exported schema, seed and generation version in your repository or job configuration. Changes to the schema, engine or source catalogs can change the result. Seeded output is intended for tests.

Up to 8 tables, 10,000 rows in total and 20,000 values per request, including array elements. The rate limit is 60 requests per minute per account.

Ready-to-run examples and setup

The examples read randby-builder-schema.json and write fixtures.json. Save the code under the filename shown in Setup. In GitHub Actions, use the workflow step after checkout and load the result in a later step.

Setup

bash --version
curl --version
jq --version
bash generate-fixtures.sh

curl + jq

set -euo pipefail
: "${RANDBY_CI_KEY:?RANDBY_CI_KEY is required}"

jq -n --slurpfile schema randby-builder-schema.json --arg seed 'fixtures-v1' \
  '{schema: $schema[0], seed: $seed, version: "v1"}' |
  curl --fail --silent --show-error --max-time 60 'https://rand.by/api/builder/ci/generate' \
    --header "Authorization: Bearer $RANDBY_CI_KEY" \
    --header 'Content-Type: application/json' \
    --data-binary @- --output fixtures.json

Errors and next steps
400	Invalid JSON, seed, version or schema. For schema errors, inspect data.code and data.field in the response.
401	The CI key is missing, invalid, expired or revoked, or Premium is inactive. Check the secret and the account.
413	The request body exceeds 260 KiB. Reduce the size of the schema.
429	The account exceeded the request limit. Wait a minute before retrying.
502	The server could not generate the dataset. Retry later if the problem persists with a valid schema.
503	Key verification is temporarily unavailable. Retry later.

API endpoints

Choose an endpoint, review its parameters and open the sandbox. Edit the query and run a GET request to inspect the actual JSON response.

The URL alone does not authorize a request. Get a token in your account and send it in the Authorization: Bearer TOKEN header. Do not put the token in the URL. To try the API without a token, use the sandbox in the documentation. How to use the API

Integer numbers

GET /api/v1/integer

Generating of positive and negative integer numbers

Parameters
Name	Description	Default value
count	Count of generated numbers (Integer number from 1 to 10000)	100
min	Left border of the range of generated numbers (Integer number from -100000000 to 100000000)	-100
max	Right border of the range of generated numbers (Integer number from -100000000 to 100000000)	100
round	Rounding the received numbers to the nearest multiples of the number specified in this field. For example, you need to get a set of numbers that are multiples of 50. So 2489 becomes 2500, 131 becomes 100, and 851 becomes 900	0

Example URL with parametershttps://rand.by/api/v1/integer?count=10