Scenario API and environment
Use the injected SDK credentials and workspace paths in Python.
A scenario runs ordinary Python with the DataMaker SDK available. The runner injects credentials and context for the run:
| Variable | Purpose |
|---|---|
DATAMAKER_API_KEY | The run's credential, used by the SDK. For raw HTTP, send it unchanged as X-API-Key. |
DATAMAKER_API_URL | API base URL for this execution. |
DATAMAKER_PROJECT_ID, DATAMAKER_TEAM_ID, DATAMAKER_SCENARIO_ID | Run scope. |
DATAMAKER_WORKSPACE_UPLOADS | Input directory synchronized before execution. |
DATAMAKER_WORKSPACE_OUTPUTS | Output directory persisted by the runner. |
DATAMAKER_RESULT_FILE | Write a JSON object here to return named values to the caller. |
Depending on where the scenario runs, the credential is either a short-lived token bound to this run or the project's scenario key. Both have project READ_WRITE privileges outside the run's own scenario, log and workspace operations. The short-lived token cannot start another scenario run. Do not print the credential, persist it in output or send it to a third-party service.
When a person starts the run, sets and datasets the script creates while it is in progress show that person as their creator. A run started by an API key credits nobody.
Generate
from datamaker import DataMaker
dm = DataMaker()
result = dm.generate_from_template_id("<template-id>", quantity=10)result is an object containing live_data and dependencies. live_data is the list of rows, one dictionary per row; iterate or export that, as in Python SDK → Read the rows.
Parameters and files
Read your scenario's configured variables with os.environ. There is no dm.params object. Read input files and write deliverables using the injected paths; see Workspace files.
Use the installed SDK's actual methods for templates, connections, endpoints and files. Method payloads differ; avoid copying placeholder calls such as export_data without constructing the body required by the API.
Return values to the caller
A caller that runs the scenario, such as a flowproof flow or a CI job, often needs a few values back: the customer number the scenario created, the order it found. Write them as one JSON object to DATAMAKER_RESULT_FILE:
import json, os
with open(os.environ["DATAMAKER_RESULT_FILE"], "w") as f:
json.dump({"customer_no": customer_no, "material": material}, f)A synchronous POST /scenarios/execute returns the object as result.data. It is ignored, with a warning in the run log, when it is not a JSON object or is larger than 256 KB. Values are masked like printed output when they contain an endpoint credential.
Raw HTTP
For an operation your SDK version does not wrap, use the configured API URL and X-API-Key. Check the HTTP status and use a timeout. The REST reference describes common routes; permissions and run-credential restrictions still apply.
For multi-step orchestration across scenarios, use an external service with a separately scoped key and the documented /scenarios/execute route.