REST API

The DataMaker REST API is the canonical surface; the SDKs and the MCP server wrap it. Use it directly when you’d rather not pull a dependency.

Base URL

https://api.datamaker.automators.com

All endpoints are HTTPS only. There’s no /v1 prefix today; we’ll version with a header if a breaking change comes.

Auth

Every request needs:

Authorization: Bearer <DM_API_KEY>

Generate a key under Settings → API Keys in the app. Keys carry the role of the user who created them. Treat them as secrets — don’t commit them, don’t paste them into chat.

Content & errors

• Content-Type: application/json for request bodies.
• 200 / 201 / 204 on success.
• 4xx with a body of { "error": { "code": "...", "message": "...", "details": {...} } }.
• 5xx with a request ID — include it when filing a support ticket.

Errors are stable on error.code. Don’t pattern-match on error.message.

Pagination

List endpoints return:

{
  "items": [ ... ],
  "next_cursor": "eyJpZ...",   // null when there's no more
  "total": 142
}

Pass ?cursor=... to get the next page.

Templates

Method	Path	Notes
GET	/templates	List templates in the project.
POST	/templates	Create.
GET	/templates/{id}	Read.
PATCH	/templates/{id}	Update fields. Creates a new version.
DELETE	/templates/{id}	Soft-delete.
GET	/templates/{id}/versions	List versions.
GET	/templates/{id}@v{n}	Read a specific version.
POST	/templates/{id}/generate	Generate rows.
POST	/templates/{id}/preview	Generate 3 rows. Cheaper, no quota debit.

POST /templates/{id}/generate body:

{
  "count":     100,
  "format":    "json" | "csv" | "sql" | "xlsx",
  "seed":      "optional-string",
  "overrides": { "country": "DE" }
}

Response: a stream of the chosen format. Use Accept: text/csv for CSV streaming.

Scenarios

Method	Path	Notes
GET	/scenarios	List.
POST	/scenarios	Create.
PUT	/scenarios/{id}	Replace code.
POST	/scenarios/{id}/run	Trigger a run.
GET	/scenarios/{id}/runs	List runs.
GET	/scenarios/{id}/runs/{run_id}	Run detail.
GET	/scenarios/{id}/runs/{run_id}/logs	Logs (text). Use ?follow=true for SSE.
DELETE	/scenarios/{id}/runs/{run_id}	Cancel.

Trigger a run:

curl -X POST https://api.datamaker.automators.com/scenarios/$SCN/run \
  -H "Authorization: Bearer $DM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": { "environment": "regression", "size": "500" },
    "wait":   "false"
  }'

"wait": "true" blocks until the run finishes (up to 5 minutes); "false" returns a run ID immediately and you poll /runs/{run_id} or stream /logs?follow=true.

Connections

Method	Path	Notes
GET	/connections	List.
POST	/connections	Create. Body shape varies by type.
POST	/connections/{id}/verify	Re-run the verification check.
GET	/connections/{id}/metadata	For SAP / OpenAPI: parsed schema.

Saved sets

Method	Path	Notes
GET	/sets	List.
POST	/sets	Save ({name, rows}). Re-using a name versions.
GET	/sets/{name}	Load.
DELETE	/sets/{name}	Remove.

Workspace files

Method	Path	Notes
GET	/workspace/files	List.
POST	/workspace/files	Multipart upload (name + file part).
GET	/workspace/files/{name}	Download.
DELETE	/workspace/files/{name}	Remove.

Rate limits

Per workspace:

Plan	Requests / minute	Generation rows / hour
Free	60	10,000
Pro	600	1,000,000
Enterprise	per contract	per contract

Each response includes X-RateLimit-Remaining and X-RateLimit-Reset. On 429 we send Retry-After.

SDKs

For most things, prefer:

• Python SDK — pip install datamaker.
• TypeScript SDK — npm install datamaker.

Both wrap this REST API and add typing, retries, and ergonomics.