The causal engine, headless.
A headless API for agencies, data teams, and agentic clients. Auth0 M2M tokens, idempotency keys, async jobs, cleaned-schema inspection, stable errors, documented retries, and retention controls. Integrate Simulacra's validated causal AI directly into your applications, or let autonomous agents use the platform directly.
Same flow, every language.
Claim credentials, mint a token, upload a dataset, poll the job, fetch the cleaned schema, submit a generation, and download the artifact.
# 1. Mint an Auth0 M2M token (omitted) → token import requests, uuid, time # 2. Upload a seed dataset files = {"file": open("tracker_q3.csv", "rb")} headers = {"Authorization": f"Bearer {token}", "Idempotency-Key": str(uuid.uuid4())} r = requests.post("https://api.simulacra-data.com/v1/datasets", files=files, headers=headers) dataset_id = r.json()["dataset_id"] job_id = r.json().get("job_id") # 3. Wait for training while True: s = requests.get(f"https://api.simulacra-data.com/v1/jobs/{job_id}", headers=headers).json() if s["status"] in ("ready", "failed"): break time.sleep(2) # 4. Inspect cleaned schema schema = requests.get(f"https://api.simulacra-data.com/v1/datasets/{dataset_id}/schema", headers=headers).json() # 5. Generate scenario-conditioned rows body = { "row_count": 2000, "conditions": { "categorical": {"segment": {"genz_switcher": 0.30}}, "numeric": {"price": {"min": 5.49, "max": 5.49}} } } g = requests.post(f"https://api.simulacra-data.com/v1/datasets/{dataset_id}/generations", json=body, headers=headers).json() # 6. Poll, download artifact_url
# 1. Mint M2M token (omitted) library(httr2) req <- request("https://api.simulacra-data.com/v1/datasets") |> req_auth_bearer_token(token) |> req_headers(`Idempotency-Key` = uuid::UUIDgenerate()) |> req_body_multipart(file = curl::form_file("tracker_q3.csv")) resp <- req |> req_perform() |> resp_body_json() dataset_id <- resp$dataset_id job_id <- resp$job_id # 2. Poll, fetch schema, generate (mirrors the Python flow)
# Upload seed curl -X POST https://api.simulacra-data.com/v1/datasets \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -F "file=@tracker_q3.csv" # Generate scenario curl -X POST https://api.simulacra-data.com/v1/datasets/$DSID/generations \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "row_count": 2000, "conditions": { "categorical": { "segment": { "genz_switcher": 0.30 } }, "numeric": { "price": { "min": 5.49, "max": 5.49 } } } }'
The canonical quickstart and full reference live at api.simulacra-data.com/__docs__/↗
An API designed by people who actually integrate APIs.
Agent discovery
/openapi.json is the contract. /llms.txt and /llms-full.txt document routing for agent clients. Stable operationId values keep generated clients predictable.
Idempotent retries
Idempotency-Key on every POST. Reusing the same key makes a retry safe; changing the key creates new work. Usage-billing reflects generated rows, not requested rows.
Async jobs: 202 means progress
Long-running training and generation return 202 Accepted with a job_id. Poll /v1/jobs/{job_id} with jittered backoff. Outputs land at artifact_url on completion.
Schema-first conditioning
Cleaning may rename or drop columns and rare levels. Always GET /v1/datasets/{id}/schema before constructing conditions — never build from your raw headers.
Stable error codes
Every problem response carries a stable code like simio_unknown_condition_column with a doc URL at /errors/{code} covering cause, fix, retryability, and support guidance.
v1 stable contract
Non-breaking additions, including optional fields, new enum values, new endpoints, and richer examples, ship without a version bump. Breaking changes receive at least 30 days' notice or move to v2.
Procurement-friendly. Zero-trust by default.
The Headless API has its own security and retention model because it intentionally retains trained artifacts for short, explicit windows. See API Security for procurement review and implementation planning.
OAuth2 client-credentials via Auth0
Tenant-scoped M2M tokens. credential_claim_token is one-time-use; rotation supported.
Encryption at rest & in transit
TLS for every request. Encrypted artifact storage with managed-mode default; enterprise customer-storage / KMS option available.
Audited operator actions
Recorder logs admin and operator actions. Health probes and security alerts on production infrastructure.
24-hour default retention
Trained-dataset and generation artifacts default to 24-hour retention. Maximum continuous dataset retention 7 days.
15-minute signed download URLs
Managed-mode download URLs expire by default at 15 minutes and require the bearer token. Enterprise URLs may route through customer storage.
Explicit DELETE semantics
DELETE /v1/datasets/{id} removes active dataset access and associated retrievable dataset artifacts from the API surface. Generation artifacts expire on their own retention windows.
Start with the docs. Or talk to us about an enterprise integration. The first 20,000 rows are on us.
Request access and run your first project through the API, or let your agent run the project for you. Enterprise API users get the first 20,000 rows on us.