> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pidgeon.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Flock API

> Synthetic population generation endpoints — connect to databases, learn patterns, generate populations, and seed data.

Twelve endpoints for synthetic population generation. All **public**.

## POST /api/flock/connect

Connect to a database and analyze its schema.

| Field              | Type   | Description                      |
| ------------------ | ------ | -------------------------------- |
| `provider`         | string | `postgres`, `mysql`, `sqlserver` |
| `connectionString` | string | Database connection string       |

```bash curl theme={null}
curl -X POST http://localhost:5102/api/flock/connect \
  -H "Content-Type: application/json" \
  -d '{"provider": "postgres", "connectionString": "Host=localhost;Port=5432;Database=ehr;Username=dev;Password=${DB_PASSWORD}"}'
```

## GET /api/flock/schema

Get the analyzed schema from the last connection.

```bash curl theme={null}
curl http://localhost:5102/api/flock/schema
```

## POST /api/flock/learn

Learn statistical patterns from existing sample data.

```bash curl theme={null}
curl -X POST http://localhost:5102/api/flock/learn \
  -H "Content-Type: application/json" \
  -d '{"tables": ["patients", "encounters"], "sampleSize": 500}'
```

## GET /api/flock/profiles

List learned profiles.

```bash curl theme={null}
curl http://localhost:5102/api/flock/profiles
```

## GET /api/flock/profiles/{name}

Get a specific profile.

```bash curl theme={null}
curl http://localhost:5102/api/flock/profiles/ehr_production
```

## POST /api/flock/generate

Start a generation job. Returns a job ID for polling.

| Field             | Type   | Default | Description                 |
| ----------------- | ------ | ------- | --------------------------- |
| `count`           | int    | `100`   | Number of patients          |
| `format`          | string | `"sql"` | `sql`, `csv`, `hl7`, `fhir` |
| `geographicFocus` | string | `"us"`  | Geographic distribution     |
| `seed`            | int    | null    | Reproducible seed           |

```bash curl theme={null}
curl -X POST http://localhost:5102/api/flock/generate \
  -H "Content-Type: application/json" \
  -d '{"count": 1000, "format": "sql", "geographicFocus": "us"}'
```

## GET /api/flock/generate/{id}

Poll job status.

```bash curl theme={null}
curl http://localhost:5102/api/flock/generate/job-123
```

## GET /api/flock/generate/{id}/analytics

Get analytics for a completed job.

```bash curl theme={null}
curl http://localhost:5102/api/flock/generate/job-123/analytics
```

## POST /api/flock/seed

Seed the connected database with generated data.

```bash curl theme={null}
curl -X POST http://localhost:5102/api/flock/seed \
  -H "Content-Type: application/json" \
  -d '{"jobId": "job-123"}'
```

## POST /api/flock/seed/dry-run

Preview SQL without executing.

```bash curl theme={null}
curl -X POST http://localhost:5102/api/flock/seed/dry-run \
  -H "Content-Type: application/json" \
  -d '{"jobId": "job-123"}'
```

## DELETE /api/flock/seed/cleanup

Remove all synthetic data from the database.

| Query Param        | Type   | Description         |
| ------------------ | ------ | ------------------- |
| `connectionString` | string | Database connection |
| `provider`         | string | Database type       |

```bash curl theme={null}
curl -X DELETE "http://localhost:5102/api/flock/seed/cleanup?connectionString=Host%3Dlocalhost%3BDatabase%3Dehr&provider=postgres"
```

## GET /api/flock/compliance/{id}

Get a compliance report for a generation job.

```bash curl theme={null}
curl http://localhost:5102/api/flock/compliance/job-123
```