Scenario API

A scenario is a Python file the runner executes as python3 main.py, with the datamaker Python SDK already installed and authenticated. Everything in the Python SDK reference is available, plus the whole Python standard library. There’s no scenario-only DSL, you write normal Python.

from datamaker import DataMaker

dm = DataMaker()   # reads the injected env (project / team / scenario / API key)

Injected environment

The runner sets these before your script runs. Rely on them, never hard-code equivalents:

Variable	What it is
DATAMAKER_API_KEY	scenario-scoped API key (the SDK uses it; for raw HTTP, send it as X-API-Key)
DATAMAKER_API_URL	base URL of the DataMaker API
DATAMAKER_PROJECT_ID / DATAMAKER_TEAM_ID / DATAMAKER_SCENARIO_ID	the run’s scope
DATAMAKER_WORKSPACE_UPLOADS	dir synced from object storage before the run (input files live here)
DATAMAKER_WORKSPACE_OUTPUTS	anything written here is persisted to object storage after the run

Generate

from datamaker import Template

# from a template object you build in code…
tmpl = Template(name="Customer", quantity=100, fields=[
    {"name": "full_name", "type": "Name"},
    {"name": "email", "type": "E-Mail"},
])
rows = dm.generate(tmpl)

# …or from a template already saved in the project, by id
rows = dm.generate_from_template_id("<template-id>", quantity=100)

See Python SDK → templates for field types and the typed field helpers (NumberField, AIField, CustomField, …).

Templates, connections & endpoints

The client exposes flat methods for the core resources, e.g.:

dm.get_templates()                                   # list
dm.create_template(template_data, project_id, team_id)
dm.get_connections()
dm.create_connection(name, connection_type, connection_string, created_by, project_id, team_id)
dm.get_endpoints()
dm.create_endpoint(endpoint_data)                    # { name, method, url, ... }

connection_type is one of db2 | postgresql | mysql | mssql | mongodb | oracle. See the SDK’s autocomplete types and the REST reference for the exact shapes.

Export

Push generated rows into a configured target:

dm.export_to_database(export_data)   # to a database connection
dm.export_to_rest(export_data)       # to a REST / API endpoint

export_data carries the target connection/endpoint id plus the payload. See the SDK’s autocomplete types for the body shape. (To push into a SAP OData entity, configure it as an endpoint/connection and let the agent drive it.)

Scenario files

Read inputs and write outputs that travel with the run (they show up in the run’s workspace files):

dm.get_scenario_files()                 # list files attached to this run
dm.read_file_by_path(key)               # read an uploaded input
dm.save_file(local_path, folder="outputs")   # persist an output
dm.create_scenario_file(name, content)  # create a file from a string/bytes
dm.download_scenario_file(file_id)

Prefer writing deliverables under DATAMAKER_WORKSPACE_OUTPUTS and reading inputs from DATAMAKER_WORKSPACE_UPLOADS.

Logging

print() is the logging mechanism. Output is captured and streamed to the run log live (see Logs). Everything else is plain Python:

print(f"generated {len(rows)} rows")
dm.export_to_database(export_data)
print("done")

Parameters & retries

There’s no bespoke dm.params or dm.retry. Use the standard library: read configuration from environment variables, and wrap a retryable step in your own loop (or a library such as tenacity, which is pip-installable via a # requirements: comment).

Errors

The SDK raises DataMakerError; let it propagate unless you intend graceful degradation:

from datamaker.error import DataMakerError

try:
    rows = dm.generate_from_template_id("missing-id", quantity=100)
except DataMakerError as e:
    print("DataMaker call failed:", e)

Operations the SDK doesn’t do directly

Some steps have no SDK method. Do them through the agent, an MCP tool, or the REST API. None of these are SDK calls:

Want to…	Do it via
Pull existing rows from SAP / a REST source	the agent (it has the SAP/REST tools), or the source’s own API with requests
Push into a SAP OData entity	a configured SAP OData connection/endpoint, driven by the agent
Mask real PII	sensitive fields on the template, or ask the agent
Trigger another scenario	POST /scenarios/{id}/run; see the REST reference

For anything the SDK lacks, you can always fall back to the REST API with requests (base URL DATAMAKER_API_URL, header X-API-Key).