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. Routes that act on a single project, such as POST /datamaker or POST /templates, resolve which one from the first of these that is present: a projectId in the request body, a projectId query parameter, the key's own project when the key is project-scoped, then the X-Project-Id header. Any one of them is enough, so a team- or user-scoped key can name the project in the header alone. A route that resolves no project answers 400.

Scope headers never expand a key's access: a project outside the key's scope is refused with 403 whichever way you name it, and a project id that does not exist is refused with 404 {"error":"Project not found"}.

Most list routes are different - they return everything in the key's scope, and you narrow them with an optional projectId query parameter rather than the header. A few GET routes still act on a single project and answer 400 without one, with a message naming the three places you can put the id: GET /keymaps, GET /keymaps/{mapName}/entries, GET /agent/context and GET /plans/capability-catalog. Those four resolve the project exactly as the single-project routes above do, so the X-Project-Id header is enough for them.

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.

The request is refused with 400 when the body is not valid JSON, quantity is missing or is not a whole number between 1 and the limit, a field's type is not a catalogue name from GET /fields (use the catalogue spelling), or a Python Script field has no options.code. Field problems are listed in issues, each naming the field.

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

live_data is an array with one object per row, keyed by field name:

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

This illustrative response shows the shape; generated values vary. Use live_data directly as the row payload rather than the whole response. Nested and Template fields produce object values, or arrays of objects when the field sets array: true (Nested objects), so flatten those rows before writing CSV, and check Limits before saving a large run as a set. dependencies is an array listing the templates, connections and endpoints that referencing fields resolved to; it is empty when none of the request's fields reference another resource.

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.
• 404: check the resource id. A projectId that does not exist is refused here rather than as a scope error.
• 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.