# Random records API

Sample synthetic records conforming to the specified record schema.

CLI equivalent: `simhealth sample {recordType} --count 1 --seed 1842`
(`--format json|ndjson|avro`, extra `--constraint key=value`).

The project ID must match the project permanently bound to the Bearer API key.
The unscoped path `GET /v1/random/{recordType}` is retained as a legacy
compatibility route for existing clients; use the project-scoped path for new
integrations.

## Request parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `recordType` | path string | required | Record definition name, such as `person` or `encounter`. |
| `count` | query integer | `1` | Number of records. Up to 10,000 for JSON and 10,000,000 for Avro. |
| `seed` | query integer | random | 64-bit unsigned seed for deterministic sampling. |
| `fields` | query string | all | Comma-separated fields to include. |

## Headers and content negotiation

- `Authorization: Bearer <SIMHEALTH_API_KEY>` is required. A signed-in Firebase ID token or an API key is enough. Omitting `x-customer-id` does not return 400.
- `x-customer-id` is an optional credit-ledger override. When omitted, the call is metered as `anonymous`. An `sk_live_...` value in this header is ignored for the ledger. Any other value must be 1–128 ASCII letters, digits, `_`, or `-`, must not be `anonymous`, and must not start with `cs_`. An invalid value is HTTP 400 `{"error":"invalid customer id","message":"invalid customer id"}`.
- `Accept: application/json` returns buffered JSON (the default), up to 10,000 records.
- `Accept: application/avro-binary` or `application/avro` returns a streaming Avro OCF, up to the caller's record quota (default ceiling 10,000,000).
- `Accept: application/x-ndjson` returns newline-delimited JSON.

The API does not guarantee a throughput rate or a client rate limit. The figures above are count caps.

## Example response

```json
{
  "recordType": "person",
  "count": 1,
  "seed": 1842,
  "records": [
    {
      "person_id": "P-981742",
      "first_name": "Maria",
      "last_name": "Santos",
      "gender": "female",
      "birth_date": "1984-06-12",
      "mrn": "MRN-004928"
    }
  ]
}
```
