REST API

The hosted API base is https://api.datamaker.automators.com. For desktop or self-hosted installations, use the API URL configured for that installation, including any base path. Set DATAMAKER_API_URL without a trailing slash for the examples below.

The API serves its interactive reference at the API origin's root and its OpenAPI document at /openapi under the configured API base path. The deployed reference describes that release. Response shapes and pagination vary by endpoint; there is no universal cursor or error envelope.

Authenticate and select a project

API keys use X-API-Key. Authorization: Bearer is for session tokens, not API keys. Create an appropriately scoped key with a workspace administrator; see API keys and permissions.

export DATAMAKER_API_URL=https://api.datamaker.automators.com
# Set DATAMAKER_API_KEY and DATAMAKER_PROJECT_ID through your secret/config store.
curl --fail-with-body "$DATAMAKER_API_URL/templates" \
  -H "X-API-Key: $DATAMAKER_API_KEY" \
  -H "X-Project-Id: $DATAMAKER_PROJECT_ID"

Keys can be scoped to a project, team or user. Supply the relevant project for operations that need one; routes may also require projectId in the body or query. Scope headers never expand a key's access.

Generate data

Generation uses POST /datamaker with field definitions and a quantity. To generate from a saved template, fetch it first and pass its fields to this route.

curl --fail-with-body "$DATAMAKER_API_URL/datamaker" \
  -H "X-API-Key: $DATAMAKER_API_KEY" \
  -H "X-Project-Id: $DATAMAKER_PROJECT_ID" \
  -H 'Content-Type: application/json' \
  --data '{"quantity":3,"seed":42,"fields":[{"name":"id","type":"UUID"},{"name":"name","type":"First Name"}]}'

The response contains columns, not an array of row objects:

{
  "live_data": {"id": ["example-id-1", "example-id-2"], "name": ["Ada", "Sam"]},
  "dependencies": {}
}

This illustrative response shows the shape; generated values vary. Convert live_data to rows before using it as a row-oriented export payload. The Python guide shows how.

The body also accepts locale, which points every generator at that locale for the request - "de", "de-AT" and "de_AT" all resolve, and a region variant the catalogue does not carry falls back to its bare language. A field's own options.locale wins over the request's. An unknown or empty code resets to the default rather than failing the request, so check the values you got back rather than assuming a locale was applied.

An integer seed reproduces internal generator output for the same fields, quantity and locale. AI, API Response, DB Response and Python Script fields depend on external execution and are outside that guarantee. There is no template-version suffix or separate /templates/{id}/generate route.

Run a saved scenario

curl --fail-with-body "$DATAMAKER_API_URL/scenarios/execute" \
  -H "X-API-Key: $DATAMAKER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg projectId "$DATAMAKER_PROJECT_ID" \
    --arg scenarioId "$DATAMAKER_SCENARIO_ID" \
    '{projectId:$projectId,scenarioId:$scenarioId,async:true,environmentVariables:{ENVIRONMENT:"test"}}')"

For hosted asynchronous execution, save the returned jobId. Poll GET /scenarios/jobs/{jobId}/status, which returns state, progress, output, error and logs: {logs, count}. Hosted states come from the queue, including waiting, delayed, active, completed and failed. Continue polling nonterminal states. Treat a run as successful only when state is completed and error is null or empty: a completed queue job can still carry a failed script result. Desktop local execution can return a runner payload instead; that payload is not a completed run and requires the desktop runner.

Use GET /scenarios/jobs/{jobId}/logs/stream for the event stream and POST /scenarios/jobs/{jobId}/cancel to request cancellation. A start response is an acknowledgment, not proof the work succeeded. See the bounded CI polling example.

Common routes

These are route names, not complete request schemas. Use the interactive reference for required parameters. In particular, /preview proxies a configured external request; it is not a template-generation preview.

Handle failures

Check the HTTP status before parsing a successful result. Error bodies may use error, message, validation details or a license-specific code; proxies can return non-JSON errors.

• 401: check credentials and the selected API host.
• 403: check permissions, project scope and any required approval.
• 402: inspect the license or usage remediation returned by the server.
• 409: inspect the resource state, such as a locked set.
• 429: honor Retry-After if supplied and reduce request frequency.

Do not automatically retry a write after an ambiguous network failure: first check the target and run record for partial completion. See Limits and Logs and retries.