Headless API

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.

Quickstart

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

The canonical quickstart and full reference live at api.simulacra-data.com/__docs__/

API built for agents and data pipelines

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.

Secure by design

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.

Ready to integrate?

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.