Examples

Six worked examples, from a single mixed-function document up to relational batch generation and template control flow. Every request below is a plain REST call — no dashboard, no SDK required.

1. Single document, mixed functions

Goal: Generate one fake user profile in a single call, combining several built-in functions in one template body.

Template body

{
  "name": "<getRandomFullName()>",
  "email": "<getRandomEmail()>",
  "age": "<getRandomNumber(18, 65)>",
  "active": "<getRandomBoolean(0.8)>"
}

curl -s -X POST http://localhost:4000/v1/templates/generate \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{
        "body": "{ \"name\": \"<getRandomFullName()>\", \"email\": \"<getRandomEmail()>\", \"age\": \"<getRandomNumber(18, 65)>\", \"active\": \"<getRandomBoolean(0.8)>\" }"
      }'

{
  "data": { "name": "...", "email": "...", "age": "34", "active": "true" },
  "meta": { "seed": ..., "generatedAt": "..." }
}

Tip

Every value here is a string — the placeholders sit inside JSON string quotes in the template body, so the substituted text stays part of that quoted string.

Tip

To get a native JSON number/boolean instead, drop the quotes around the placeholder in the template body, e.g. { "age": <getRandomNumber(18, 65)>, "active": <getRandomBoolean(0.8)> } → { "age": 34, "active": true }.

2. Reusable template + reproducible output via seed

Goal: Save a template once, generate from it repeatedly, and reproduce the exact same output later by replaying the seed returned in a previous response.

Template body ("order")

{ "total": "<getRandomNumber(10,500,2)>" }

# 1. Create the template
curl -s -X POST http://localhost:4000/v1/templates \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{ "name": "order", "body": "{ \"total\": \"<getRandomNumber(10,500,2)>\" }" }'
# -> returns templateId

# 2. Generate
curl -s -X POST http://localhost:4000/v1/templates/<templateId>/generate \
  -H 'Authorization: Bearer sk_...' -d '{}'
# -> returns data and meta.seed, e.g. meta.seed: 12345

# 3. Reproduce the exact same data later
curl -s -X POST http://localhost:4000/v1/templates/<templateId>/generate \
  -H 'Authorization: Bearer sk_...' -d '{ "seed": 12345 }'

{ "data": { "total": "..." }, "meta": { "seed": 12345, "templateId": "...", "generatedAt": "..." } }

3. Sequence-backed unique order numbers

Goal: Generate unique, incrementing order numbers using a named sequence, either inline in one template or managed as a standalone sequence.

Inline, simplest — no separate sequence management

{ "orderNo": "<createSeq('orderNo', 'number', 1000, 1)><getSeq('orderNo')>" }

# 1. Create the sequence once
curl -s -X POST http://localhost:4000/v1/sequences \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{ "name": "orderNo", "type": "number", "start": 1000, "step": 1 }'

# 2. Reference it from any template body
# { "orderNo": "<getSeq('orderNo')>" }

# 3. Advance it without generating a document
curl -s -X POST http://localhost:4000/v1/sequences/orderNo/bump \
  -H 'Authorization: Bearer sk_...'

{ "data": { "orderNo": "1000" }, "meta": { "seed": ..., "generatedAt": "..." } }

Tip

createSeq is a setup call and produces no value by itself — getSeq is what returns the current value. Call createSeq once, then reference getSeq from any template that needs the next number.

See also: createSeq, getSeq, Sequences API

4. Batch generation with relations (parent + child documents)

Goal: Generate one customer and 3 orders in a single batch, where each order automatically gets that customer’s id injected onto it.

Templates (already created)

# customer template body
{ "id": "<createSeq('customerId')><getSeq('customerId')>", "name": "<getRandomFullName()>" }

# order template body — does NOT reference the relation field itself;
# the batch engine injects it after generation
{ "total": "<getRandomNumber(10,500,2)>" }

curl -s -X POST http://localhost:4000/v1/batches \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{
        "documents": [
          { "templateId": "<customerTemplateId>", "alias": "customer", "count": 1 },
          {
            "templateId": "<orderTemplateId>",
            "alias": "order",
            "count": 3,
            "relations": { "customerId": { "from": "customer.id", "strategy": "round-robin" } }
          }
        ]
      }'

# Each generated "order" document gets a "customerId" field added
# (overwritten if already present) with the referenced "customer"
# document's id value. Response is 200 with "results" if the batch is
# small/synchronous, or 202 — poll GET /v1/batches/{batchId} until it
# completes.

Tip

relations is an object keyed by the field to set on the child document. A plain string "<parentAlias>.<dotted.field.path>" is only valid when the parent’s count is 1 — using it against a parent with count > 1 is rejected with AMBIGUOUS_RELATION at submit time.

Tip

When the parent’s count > 1, use the object form { "from": "...", "strategy": "round-robin" } — each child document is matched to a parent document by index, wrapping around (childIndex % parentCount). "round-robin" is the only supported strategy today; anything else is rejected with UNSUPPORTED_STRATEGY.

Tip

getContext(name) is reserved in the template engine for a possible future relations mechanism, but batches do not currently pass any context into child-template generation — calling it inside a batch child template fails with "no relational context value". Use relations instead.

5. Ad hoc generation for quick exploration

Goal: Test a function or a document shape without saving a template first — useful while iterating on a template body.

curl -s -X POST http://localhost:4000/v1/templates/generate \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{ "body": "{ \"code\": \"<appendBefore(\'0\', getRandomNumber(1,999), 5)>\" }" }'

{ "data": { "code": "00042" }, "meta": { "seed": ..., "generatedAt": "..." } }

Tip

Still counts toward usage even though nothing is persisted.

6. Conditional / loop template body (advanced, less common)

Goal: Build a field whose value depends on a counted position, using a for loop and an if/else conditional inside the template body.

Template body

{ "label": "<for(i,1,3)><if(getVar(i)==1)><getVar(i)>-first<else><getVar(i)>-rest<endIf><end_for>" }

curl -s -X POST http://localhost:4000/v1/templates/generate \
  -H 'Authorization: Bearer sk_...' \
  -H 'content-type: application/json' \
  -d '{ "body": "{ \"label\": \"<for(i,1,3)><if(getVar(i)==1)><getVar(i)>-first<else><getVar(i)>-rest<endIf><end_for>\" }" }'

{ "data": { "label": "1-first2-rest3-rest" }, "meta": { "seed": ..., "generatedAt": "..." } }

Tip

The if/else branch bodies must each contain a real placeholder call — a template must have at least one placeholder overall, and literal-only branches (e.g. bare "first"/"rest" text with no function call) don’t count. A loop/conditional built only from literal branch text is rejected with NO_PLACEHOLDERS even though the if condition itself calls a function. That’s why <getVar(i)> appears inside each branch above rather than relying on the condition alone.

Tip

getVar(i) (not bare i) is required to read the loop variable’s value — a bare identifier like i evaluates to the literal string "i", not the loop’s current value, so <if(i == 1)> would silently always be false.

Tip

Most templates don’t need control flow — prefer plain per-field functions first, and reach for loops/conditionals only when a field’s value genuinely depends on a counted position or another field’s value.

Ready to try these against your own data?

Get your API key Browse function reference