Datumly API

Deterministic sample data over a simple REST API. No SDK required — if you can make an HTTP request, you can generate JSON, CSV, or SQL data with repeatable seeds.

Quickstart

Every dataset is one GET away. Anonymous requests need no key and return up to 1,000 rows.

curl "https://datumly.ashusevim.dev/api/datasets?dataset=ecommerce-orders&rows=25&seed=acme-demo"

Authentication

Create a key at /account and send it as a bearer header (or ?api_key=). Keys unlock higher limits and monthly quota tracking; a raw key is shown once at creation and only its hash is stored.

curl -H "Authorization: Bearer dl_live_…" \
  "https://datumly.ashusevim.dev/api/datasets?dataset=saas-users&rows=5000&format=csv"

Invalid or revoked keys return 401 — anonymous limits are never silently applied.

Endpoint

GET /api/datasets

Param	Type	Default	Description
`dataset`	string	ecommerce-orders	Dataset slug, `custom` for Pro schemas, see the list below
`rows`	int 1–plan cap	10	Number of rows to generate (leaf rows for relational bundles)
`seed`	string	datumly	Deterministic seed — same seed, same data
`format`	string	json	`json`, `csv`, or `sql`
`bundle`	bool	false	For relational datasets + JSON: return linked tables instead of denormalized rows
`fields`	JSON	—	Pro only with `dataset=custom`: array of `{ key, type }`
`date_from`	ISO date	rolling window	Lower bound of generated dates (inclusive)
`date_to`	ISO date	rolling window	Upper bound of generated dates (inclusive-ish)

Every response includes x-datumly-plan and x-datumly-rows-remaining headers so you can track your quota without an extra call. Custom schemas also accept POST /api/datasets with a JSON body.

Datasets

Slug	Category	Description
`ecommerce-orders`	Commerce	Realistic purchases with customers, products, payment states, and order totals.
`saas-users`	SaaS	User accounts with plans, engagement, subscription state, and signup details.
`product-catalog`	Commerce	Inventory-ready products with SKUs, prices, stock levels, and categories.
`financial-transactions`	Finance	Account activity with merchants, transaction types, currencies, and balances.
`support-tickets`	Operations	Customer support cases with priorities, agents, categories, and resolution status.
`web-analytics`	Analytics	Page-view events with sessions, devices, traffic sources, and conversions.
`crm-pipeline`	Sales · relational	Linked companies, contacts, and deals — shared IDs stay consistent across rows and bundle tables.
`project-tasks`	Operations · relational	Projects, assignees, and tasks with stable foreign keys — ideal for multi-table fixtures.

Custom schemas (Pro)

Send your own field list — the same seven types as the schema builder — and get deterministic rows through the API. Requires a Pro API key. Prefer POST for larger schemas; GET with a URL-encoded fields param works for small ones.

curl -X POST "https://datumly.ashusevim.dev/api/datasets" \
  -H "Authorization: Bearer dl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "leads",
    "rows": 50,
    "seed": "acme-demo",
    "fields": [
      { "key": "id", "type": "uuid" },
      { "key": "email", "type": "email" },
      { "key": "company", "type": "string" },
      { "key": "score", "type": "integer" }
    ]
  }'

Relational bundles

Relational datasets keep foreign keys stable across rows. Add bundle=1 with format=json to receive separate linked tables (for example companies, contacts, and deals) instead of a single denormalized list. CSV and SQL always export the denormalized leaf rows.

curl "https://datumly.ashusevim.dev/api/datasets?dataset=crm-pipeline&rows=25&seed=acme-demo&bundle=1"

Determinism

Generation is seeded, not random. By default dates come from a rolling trailing-18-months window that advances monthly — your demo data stays fresh. For byte-identical output forever, pin the window:

# Byte-identical output, forever
curl "https://datumly.ashusevim.dev/api/datasets?dataset=ecommerce-orders&rows=100&seed=acme-demo&date_from=2026-01-01&date_to=2026-09-01" \
  | md5sum   # d0f1c6…  — same value on every machine, every run

Plans & limits

No account? Every endpoint works anonymously at 1,000 rows per request.

Plan	Max rows / request	Rows / month	Price
Hobby	1,000	500,000	$0/mo
Pro	10,000	2,000,000	$9/mo

Errors

Status	Meaning
`401`	API key is invalid or revoked
`403`	Custom schemas requested without a Pro plan
`404`	Unknown dataset slug
`429`	Monthly row quota exhausted — upgrade or wait for the next period

{
  "error": "Monthly row quota exceeded",
  "limit": 500000,
  "used": 500000
}