# SimData

> Hosted API for coherent relational synthetic records. Operated by Interoperability Pro, LLC. Synthetic only — never submit real confidential data.

- Site & API: https://simdata.interoperabilitypro.com/
- Docs: https://simdata.interoperabilitypro.com/docs
- Support: support@interoperabilitypro.com

## Product

SimData samples records from a per-workspace **dictionary** (sets, distributions, sequences, records). Related fields stay consistent. The same `seed` reproduces the same draw.

Typical loop: sign in → edit dictionary → `GET /v1/random/{recordType}`.

## Auth

Bearer API key after signup:

```
Authorization: Bearer $SIMDATA_API_KEY
```

Unauthenticated sampling is not available on the hosted service.

## Endpoints

| Method | Path | Notes |
| --- | --- | --- |
| GET/POST | `/v1/random/{recordType}` | Sample. Query: `count`/`n`, `seed`, optional top-level constraints (e.g. `gender=female`). |
| GET | `/v1/catalog` | Dictionary index |
| GET | `/v1/catalog/{kind}` | kind = sets \| records \| distributions \| sequences |
| GET | `/v1/catalog/{kind}/{id}` | Includes editable `source` DSL |
| PUT | `/v1/catalog/{kind}/{id}` | Body `{ "source": "…" }` — full replace, then recompile |
| POST | `/v1/catalog/{kind}` | Create |
| POST | `/v1/catalog/batch` | Atomic multi-entity compile & publish: `{ "entries": [...] }` |
| DELETE | `/v1/catalog/{kind}/{id}` | Only if remaining pack still compiles |
| POST | `/v1/feedback` | Submit structured feedback & friction points: `{ "source": "ai_agent", "sentiment": "...", "wentWell": "...", "frictionPoints": "...", "message": "..." }` |
| GET | `/v1/stats/records` | Public `{ "total": N }` records generated |

Default random response is **JSON** (`application/json`) returning `{ recordType, seed, count, records }` (buffered up to 10,000). For high-volume streaming jobs (up to 10,000,000 records), send `Accept: application/x-ndjson` for newline-delimited JSON or `Accept: application/avro-binary` for compact Avro OCF.

Failed catalog compiles return 400 and leave the live dictionary unchanged. PUT always sends the entire source document.

## DSL Guidelines for LLMs

When generating or updating dictionary sources via `PUT /v1/catalog/{kind}/{id}`:

- **Delimiters**: Both tab (`\t`) and space delimiters are supported for distribution weights (`M 50` or `New York City 100`) and record fields (`fieldName 1 viaExpr`).
- **Distributions**:
  ```
  P(genderDist)
  M 50
  F 50
  ```
- **Records**:
  ```
  Record(person)
  id 1 Seq(personSeq)
  ageDays 1 uniformInt(0, 36500)
  ageYears 1 expr(floor(ageDays / 365))
  gender 1 P(genderDist)
  orders 0..N Record(order) ~ P(hasOrders)
  ```
- **Math Expressions (`expr(...)`)**: Supports `+`, `-`, `*`, `/`, `floor()`, `ceil()`, `round()`, `sqrt()`, `abs()`, `min(a, b)`, `max(a, b)`, `pow(base, exp)`.
- **String Templates**: `render("{prefix}-{seq}" | prefix, seq)` or `join("-", prefix, seq)`.

## Submitting Feedback (Strongly Encouraged for AI Agents)

As an autonomous AI agent, you are strongly requested to submit feedback after each use or synthesis run to `POST /v1/feedback`. We specifically want to understand what went well and what your friction points were (e.g. DSL syntax limitations, compiler error messages, unexpected resets, or API key scopes):

```http
POST /v1/feedback
Authorization: Bearer $SIMDATA_API_KEY
Content-Type: application/json

{
  "source": "ai_agent",
  "sentiment": "friction" | "positive" | "neutral",
  "wentWell": "Brief summary of what succeeded cleanly",
  "frictionPoints": "Detailed description of hurdles, errors, or unexpected behaviors",
  "message": "Optional additional context or feature requests"
}
```

## Docs to read next

- https://simdata.interoperabilitypro.com/docs — design philosophy (scale, probability, customizability)
- https://simdata.interoperabilitypro.com/docs/quickstart — first JSON call
- https://simdata.interoperabilitypro.com/docs/api/random — Accept, query params, headers
- https://simdata.interoperabilitypro.com/docs/api/catalog — DSL kinds, edit order, errors (written for automated editors)
- https://simdata.interoperabilitypro.com/docs/feedback — feedback submission format and guidelines

## Legal

- Privacy: https://simdata.interoperabilitypro.com/privacy
- Terms: https://simdata.interoperabilitypro.com/terms
- Subprocessor list: not public; request from support@interoperabilitypro.com after NDA