# Simulacra Headless API

> Operating guide for the Simulacra Headless API.



## Canonical URLs

- [Interactive API docs](https://api.simulacra-data.com/__docs__/)

- [OpenAPI JSON, primary contract](https://api.simulacra-data.com/openapi.json)

- [Error catalog](https://api.simulacra-data.com/errors)

- [Full agent operating manual](https://api.simulacra-data.com/llms-full.txt)

- [Health check](https://api.simulacra-data.com/healthz)



Use HTTPS endpoints and `/openapi.json` as the machine-readable

contract for this API.



## Core Workflow

1. If credentials do not exist: `POST /v1/signup`, poll

   `/v1/signup/{request_id}`, then claim the one-time secret at

   `POST /v1/credential-claims`.

2. Mint an Auth0 machine-to-machine bearer token.

3. `POST /v1/datasets` with a seed file and an `Idempotency-Key`.

4. Poll `/v1/jobs/{job_id}` when the response is async.

5. GET `/v1/datasets/{dataset_id}/schema` before conditioning.

6. POST `/v1/datasets/{dataset_id}/generations` with an

   `Idempotency-Key`.

7. Poll `/v1/jobs/{job_id}` or `/v1/generations/{generation_id}`.

8. Download `artifact_url` after status is `ready` or `partial`.



## Retry And Polling

- Treat `202 Accepted` as progress, not failure.

- Poll every 2 seconds in examples; production agents should use

  jittered exponential backoff with a deadline.

- Retry transient `429`, `500`, `502`, `503`, and `504` only with the

  same `Idempotency-Key` for POST requests.

- Do not retry `400`, `401`, `402`, `403`, or `404` without changing

  the request.

- When an error body includes `code`, fetch `/errors/{code}` before

  deciding whether the request is retry-safe.



## Coding Agent Rules

- Treat `/openapi.json` as canonical.

- Prefer stable `operationId` values over path-derived names.

- Follow OpenAPI Links when choosing the next operation.

- Generate clients from `/openapi.json` when useful.

- Reuse helper patterns for token minting, idempotent POST retries,

  polling, schema-first conditions, downloads, and problem-code handling.

- Treat operations with `x-openai-isConsequential: true` as

  customer-affecting actions that require explicit user intent.

- Use idempotency keys on POST retries.

- Do not guess categorical levels or numeric ranges; fetch schema.

- Categorical condition values are desired outcome percentages, not internal model parameters.

- Numeric conditions require both `min` and `max`.

- Tight scenarios can produce fewer rows than requested even when

  quota remains; usage-billing is counted on generated rows rather

  than requested rows.

- Preserve `X-Request-Id`, body `request_id`, `job_id`, `dataset_id`,

  and `generation_id` for support.

- Preserve problem `code` and `type`; they are stable diagnostics.

- Never log bearer tokens, client secrets, customer data, claim tokens,

  or artifact URLs.



## Security And Retention Defaults

- Access is company-approved and authenticated with Auth0 M2M tokens.

- SLA, privacy, data-processing, and security-documentation terms are

  governed by each customer's enterprise agreement.

- Dataset and artifact retention are explicit API lifecycle concepts;

  do not assume indefinite storage.