### Install All Golden Suite Tools Together

Source: https://bensevern.dev/docs/getting-started/installation

Install all five Golden Suite tools in a single command using pip. This is a convenient way to get the entire suite.

```bash
pip install goldenmatch goldenpipe goldencheck goldenflow infermap
```

--------------------------------

### PostgreSQL Destination Configuration

Source: https://bensevern.dev/docs/api/destinations

Configuration example for a PostgreSQL destination. Credentials are embedded in the connection string.

```text
connection_string: postgres://user:pw@host:5432/dbname
target_table: required, e.g. public.golden_customers
config_json: none
credentials: none (embedded in connection string)
```

--------------------------------

### MySQL Destination Configuration

Source: https://bensevern.dev/docs/api/destinations

Configuration example for a MySQL destination. Credentials are embedded in the connection string.

```text
connection_string: mysql://user:pw@host:3306/dbname
target_table: required
config_json: none
credentials: none
```

--------------------------------

### List Entities Response Example

Source: https://bensevern.dev/docs/api/entities

Example JSON response when listing entities. Includes a list of entities with basic information and the total count.

```json
{
  "entities": [
    {
      "id": "ent_01",
      "type": "customer",
      "name": "Acme Corp",
      "member_count": 3,
      "created_at": "2026-03-20T14:00:00Z"
    }
  ],
  "total": 1842
}
```

--------------------------------

### Install Individual Golden Suite Tools

Source: https://bensevern.dev/docs/getting-started/installation

Install each of the five Golden Suite tools separately using pip. Ensure you have Python 3.10+ and pip installed.

```bash
pip install goldenmatch
pip install goldenpipe
pip install goldencheck
pip install goldenflow
pip install infermap
```

--------------------------------

### BigQuery Destination Configuration

Source: https://bensevern.dev/docs/api/destinations

Configuration example for a BigQuery destination. Requires 'service_account' credentials with a JSON payload.

```text
connection_string: bigquery://project/dataset
target_table: required, table name only
config_json: none
credentials: service_account with {key_json} (full JSON blob)
```

--------------------------------

### TypeScript Client: List and Run Destinations

Source: https://bensevern.dev/docs/api/destinations

Example of using the TypeScript client to list available destinations and run a specific one. Handles quota exceeded events automatically.

```typescript
import {
  listDestinations,
  createDestination,
  runDestination,
  exportEntities,
  storeDestinationCredential,
} from '@/lib/destinations'

// Push every golden person to the warehouse
const destinations = await listDestinations(token)
const warehouseDest = destinations.find(d => d.name === 'Warehouse · golden_customers')
const result = await runDestination(token, warehouseDest!.id)
console.log(`wrote ${result.rows_written} rows`)

// Or a one-shot browser download
const blob = await exportEntities(token, 'person', 'parquet')

```

--------------------------------

### Sample S3 Bucket Layout

Source: https://bensevern.dev/docs/guides/integrations/s3

An example of a common S3 bucket structure with daily partitioned exports, suitable for configuring the Golden Suite S3 connector with a prefix.

```text
s3://your-bucket/exports/customers/
  ├── 2026-05-10/customers.parquet
  ├── 2026-05-11/customers.parquet
  ├── 2026-05-12/customers.parquet
  └── ...

```

--------------------------------

### Snowflake Destination Configuration

Source: https://bensevern.dev/docs/api/destinations

Configuration example for a Snowflake destination. Credentials are embedded in the connection string.

```text
connection_string: snowflake://user:pw@account/DB/SCHEMA?warehouse=WH&role=ROLE
target_table: required, e.g. GOLDEN_CUSTOMERS (case preserved)
config_json: none
credentials: none
```

--------------------------------

### GET /api/demo/download

Source: https://bensevern.dev/docs/api/demo

Download the results of a demo session as a CSV file.

```APIDOC
## GET /api/demo/download

### Description
Download the results of a demo session as a CSV file.

### Method
GET

### Endpoint
/api/demo/download

### Parameters
#### Query Parameters
- **session_id** (string) - Yes - Session ID from a previous upload

### Response
#### Success Response (200)
Returns a `text/csv` file with matched and scored records.

### Request Example
```bash
curl "https://backend-production-5c86.up.railway.app/api/demo/download?session_id=abc123" \
  -o results.csv
```

### Errors
- **404 Not Found**: Session ID not found or expired
```

--------------------------------

### Salesforce Source Configuration Example

Source: https://bensevern.dev/docs/guides/integrations/salesforce

This is a sample configuration for a Salesforce source, typically generated by the autoconfig wizard. It specifies the source type, object type, credential type, fields to pull, incremental field, and page size.

```yaml
source_config = {
    "source_type": "salesforce",
    "object_type": "Lead",          # or Contact, Account
    "credential_type": "oauth",
    "fields_to_pull": [
        "Id", "Email", "Phone",
        "FirstName", "LastName", "Title",
        "Company", "LeadSource",
        "CreatedDate", "LastModifiedDate",
    ],
    "incremental_field": "LastModifiedDate",
    "page_size": 200,
}
```

--------------------------------

### Verify Golden Suite Installation

Source: https://bensevern.dev/docs/getting-started/installation

Verify that the goldenmatch tool has been installed correctly by checking its version. This command runs a Python one-liner.

```python
python -c "import goldenmatch; print(goldenmatch.__version__)"
```

--------------------------------

### Wikilink Syntax Examples

Source: https://bensevern.dev/docs/knowledge/wikilinks

Demonstrates the different ways to format Obsidian wikilinks, including linking to a specific repository note and using a custom display label with the pipe separator.

```markdown
[[repos/foo/note]]
```

```markdown
[[repos/foo/note|Foo]]
```

```markdown
[[papers/bpid-2024]]
```

--------------------------------

### Example Survivorship Rules Request Body

Source: https://bensevern.dev/docs/api/survivorship

Provides an example of the JSON payload required to replace the survivorship rules. It includes field, strategy, and priority for each rule.

```json
[
  { "field": "name", "strategy": "most_recent", "priority": 1 },
  { "field": "email", "strategy": "most_complete", "priority": 2 },
  { "field": "phone", "strategy": "manual", "priority": 3 }
]
```

--------------------------------

### Deep-linking to Entity Page with Focus

Source: https://bensevern.dev/docs/knowledge/entity-pages

This example shows how to link to an entity page and focus on a specific entity on the map using the '?focus' query parameter.

```url
/knowledge?focus=repo-benzsevern-goldencheck
```

--------------------------------

### Sample CSV Data

Source: https://bensevern.dev/docs/guides/integrations/csv-upload

This is an example of a CSV file structure that the auto-config can process. It includes common fields like id, email, and timestamps.

```csv
id,email,first_name,last_name,company,phone,created_at
1,sarah@acme.com,Sarah,Johnson,Acme Corp,+1-415-555-0100,2024-03-15
2,sarah.j@acmecorp.com,Sarah,Johnson-Smith,"Acme, Inc.",4155550100,2024-08-22
3,bob@example.com,Robert,Smith,Example LLC,+15555550200,2024-01-10

```

--------------------------------

### Infermap Demo Schema Mapping

Source: https://bensevern.dev/docs/tools/infermap

An example of using infermap for a demo scenario, mapping a CSV file to a schema containing 'name', 'email', and 'phone'. This can be run directly.

```python
import infermap
mapping = infermap.map_schema("data.csv", target_schema=["name", "email", "phone"])
print(mapping)
```

--------------------------------

### Snowflake SQL Setup for Golden Suite

Source: https://bensevern.dev/docs/guides/integrations/snowflake

SQL commands to create a dedicated warehouse, role, user, and grant necessary permissions for the Golden Suite connector in Snowflake. Ensure to replace '<paste-public-key>' with your actual public key.

```sql
-- Run as ACCOUNTADMIN once
CREATE WAREHOUSE GOLDEN_SUITE_WH WITH WAREHOUSE_SIZE = 'XSMALL' AUTO_SUSPEND = 60;
CREATE ROLE GOLDEN_SUITE_READER;
CREATE USER goldensuite_user
    LOGIN_NAME = 'goldensuite_user'
    DEFAULT_ROLE = GOLDEN_SUITE_READER
    DEFAULT_WAREHOUSE = GOLDEN_SUITE_WH
    RSA_PUBLIC_KEY = '<paste-public-key>';
GRANT ROLE GOLDEN_SUITE_READER TO USER goldensuite_user;
GRANT USAGE ON WAREHOUSE GOLDEN_SUITE_WH TO ROLE GOLDEN_SUITE_READER;
GRANT USAGE ON DATABASE PROD TO ROLE GOLDEN_SUITE_READER;
GRANT USAGE ON SCHEMA PROD.ANALYTICS TO ROLE GOLDEN_SUITE_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA PROD.ANALYTICS TO ROLE GOLDEN_SUITE_READER;
GRANT SELECT ON FUTURE TABLES IN SCHEMA PROD.ANALYTICS TO ROLE GOLDEN_SUITE_READER;

```

--------------------------------

### Ingest Support Source

Source: https://bensevern.dev/docs/guides/entity-resolution-workflow

Load the support data source into the Golden Suite via the API. Each source gets its own namespace for traceability.

```bash
curl -X POST https://api.goldensuite.dev/v1/sources \
  -H "Authorization: Bearer $GOLDEN_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@support_export.csv" \
  -F "name=support" \
  -F "namespace=source_support"

```

--------------------------------

### S3 Destination Configuration

Source: https://bensevern.dev/docs/api/destinations

Configuration example for an S3 destination. Requires 'aws_iam' credentials. The format can be auto-set from the connection string suffix.

```text
connection_string: s3://bucket/path/to/file.parquet (or .csv)
target_table: ignored
config_json: {format: "csv" | "parquet"} — auto-set from URL suffix
credentials: aws_iam with {access_key_id, secret_access_key, region}
```

--------------------------------

### Basic Schema Mapping

Source: https://bensevern.dev/docs/tools/infermap

Demonstrates the basic usage of infermap to map columns from a source CSV file to a target schema. Ensure infermap is installed via pip.

```python
import infermap

mapping = infermap.map_schema(
    source="raw_data.csv",
    target_schema=["first_name", "last_name", "email", "phone"]
)
print(mapping)

```

--------------------------------

### Configure Survivorship Rules

Source: https://bensevern.dev/docs/guides/entity-resolution-workflow

Define survivorship rules to determine which source's value wins for each field in the final golden record. This example sets rules for name, email, phone, address, created_at, and lifetime_value.

```bash
curl -X POST https://api.goldensuite.dev/v1/survivorship \
  -H "Authorization: Bearer $GOLDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "match_job_id": "job_abc123",
    "rules": {
      "name": {"strategy": "most_complete"},
      "email": {"strategy": "most_recent"},
      "phone": {"strategy": "most_recent"},
      "address": {"strategy": "source_priority", "order": ["billing", "crm", "support"]},
      "created_at": {"strategy": "earliest"},
      "lifetime_value": {"strategy": "aggregate", "function": "sum"}
    }
  }'

```

--------------------------------

### Basic Pipeline Construction

Source: https://bensevern.dev/docs/tools/goldenpipe

Demonstrates how to initialize a pipeline with a data source and add multiple transformation steps.

```python
import goldenpipe

pipe = goldenpipe.Pipeline("raw_data.csv")
pipe.add_step("normalize_names")
pipe.add_step("standardize_addresses")
pipe.add_step("deduplicate_emails")
result = pipe.run()

```

--------------------------------

### Get Audit History Response

Source: https://bensevern.dev/docs/api/audit

This is an example of the response when retrieving the signed-in user's past audits. It returns a list of audit objects, each containing audit ID, repository URL, status, entity ID, and creation timestamp.

```json
[
  {
    "audit_id": "3f2a7b8e-...",
    "repo_url": "https://github.com/owner/repo",
    "status": "complete",
    "entity_id": "repo-owner-repo",
    "created_at": "2026-04-20T13:45:12+00:00"
  }
]
```

--------------------------------

### Running a GoldenPipe Demo

Source: https://bensevern.dev/docs/tools/goldenpipe

Shows how to run a simple pipeline with a single step and print a summary of the results. This is useful for quick testing and demonstration.

```python
import goldenpipe
pipe = goldenpipe.Pipeline("data.csv")
pipe.add_step("normalize_names")
result = pipe.run()
print(result.summary())

```

--------------------------------

### Merge Entities Response Example

Source: https://bensevern.dev/docs/api/entities

Example JSON response after successfully merging two entities. Returns the ID of the merged entity.

```json
{
  "merged_entity_id": "ent_01"
}
```

--------------------------------

### Merge Entities Request Example

Source: https://bensevern.dev/docs/api/entities

Example JSON request body for merging two entities. Specifies the source entity to be merged from and the target entity to merge into.

```json
{
  "source_id": "ent_02",
  "target_id": "ent_01"
}
```

--------------------------------

### Retrieve Single Entity Response Example

Source: https://bensevern.dev/docs/api/entities

Example JSON response for retrieving a single entity. Details include the golden record, member records, and lineage information.

```json
{
  "id": "ent_01",
  "type": "customer",
  "golden_record": {
    "name": "Acme Corp",
    "email": "info@acme.com",
    "phone": "+1-555-0100"
  },
  "members": [
    {
      "source_id": "src_01",
      "source_name": "CRM Export",
      "record": { "name": "Acme Corporation", "email": "info@acme.com" }
    }
  ],
  "lineage": {
    "name": { "source": "src_01", "strategy": "most_recent" },
    "email": { "source": "src_01", "strategy": "most_complete" },
    "phone": { "source": "src_02", "strategy": "source_priority" }
  }
}
```

--------------------------------

### Run GoldenCheck Demo

Source: https://bensevern.dev/docs/tools/goldencheck

This command initiates a demo of GoldenCheck. It's a quick way to try out the tool's profiling capabilities. The underlying profiling logic is the same as the basic usage snippet.

```bash
goldencheck demo

```

--------------------------------

### List All Projects

Source: https://bensevern.dev/docs/api/workbench

Fetches a list of all projects accessible to the authenticated user. Each project entry includes its ID, name, scope, default trust level, active notebook ID, and creation timestamp.

```json
[
  {
    "id": "proj_01",
    "name": "Q1 Customer Dedup",
    "scope_type": "workspace",
    "scope_id": "ws_01",
    "default_trust": "gated",
    "active_notebook_id": "nb_01",
    "created_at": "2026-04-01T09:00:00Z"
  }
]

```

--------------------------------

### GET /api/demo/audit/{audit_id}

Source: https://bensevern.dev/docs/api/audit

Poll for the status and results of a specific audit. This endpoint does not require authentication.

```APIDOC
## GET /api/demo/audit/{audit_id}

### Description
Poll for audit status and results. No auth required.

### Method
GET

### Endpoint
/api/demo/audit/{audit_id}

### Parameters
#### Path Parameters
- **audit_id** (string) - Required - The unique identifier of the audit to poll.

### Response
#### Success Response (200)
- **audit_id** (string) - The unique identifier for the audit.
- **repo_url** (string) - The GitHub URL that was audited.
- **status** (string) - The current status of the audit (e.g., `queued`, `ingesting`, `indexing`, `critiquing`, `complete`, `failed`).
- **stage** (string) - The current stage of the audit process.
- **neighbors** (array) - A list of related entities with scores.
  - **entity_id** (string) - The ID of the related entity.
  - **title** (string) - The title of the related entity.
  - **score** (number) - The relevance score.
- **markdown** (string) - The audit critique in Markdown format.
- **error** (string or null) - Any error message if the audit failed.
- **entity_id** (string) - The unique identifier for the entity in the knowledge graph.
- **created_at** (string) - The timestamp when the audit was created.

### Response Example
```json
{
  "audit_id": "3f2a7b8e-...",
  "repo_url": "https://github.com/owner/repo",
  "status": "complete",
  "stage": "complete",
  "neighbors": [
    { "entity_id": "repo-other", "title": "...", "score": 0.89 }
  ],
  "markdown": "## Review\n\n...",
  "error": null,
  "entity_id": "repo-owner-repo",
  "created_at": "2026-04-20T13:45:12+00:00"
}
```

**Note:** Responses include `Cache-Control: no-store` — clients should poll rather than cache.
```

--------------------------------

### Create New Notebook

Source: https://bensevern.dev/docs/api/workbench

Creates a new notebook within a specified project. Requires the `project_id` and a `name` for the new notebook.

```json
{
  "project_id": "proj_01",
  "name": "Experiment A"
}

```

--------------------------------

### Create BigQuery Service Account and Grant Permissions

Source: https://bensevern.dev/docs/guides/integrations/bigquery

Use gcloud commands to create a dedicated service account, assign BigQuery dataViewer and jobUser roles, and generate a JSON key file.

```bash
gcloud iam service-accounts create goldensuite-reader \
  --display-name "Golden Suite read-only"
gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="serviceAccount:goldensuite-reader@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"
gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="serviceAccount:goldensuite-reader@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"
gcloud iam service-accounts keys create gs-key.json \
  --iam-account=goldensuite-reader@YOUR_PROJECT.iam.gserviceaccount.com
```

--------------------------------

### GET /api/survivorship/rules

Source: https://bensevern.dev/docs/api/survivorship

Retrieve the current survivorship rules. These rules define how to resolve conflicts for each field when building a golden record.

```APIDOC
## GET /api/survivorship/rules

### Description
Retrieve the current survivorship rules. These rules define how to resolve conflicts for each field when building a golden record.

### Method
GET

### Endpoint
/api/survivorship/rules

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **field** (string) - Column or attribute name
- **strategy** (string) - Survivorship strategy applied to this field
- **priority** (integer) - Evaluation order (lower = higher priority)

#### Response Example
```json
[
  { "field": "name", "strategy": "most_recent", "priority": 1 },
  { "field": "email", "strategy": "most_complete", "priority": 2 },
  { "field": "phone", "strategy": "source_priority", "priority": 3 }
]
```
```

--------------------------------

### Regenerate Knowledge Map

Source: https://bensevern.dev/docs/knowledge

Use this command to rebuild the static 2D map from backend embeddings. Ensure all specified dependencies are installed.

```bash
uv run --with numpy --with umap-learn --with python-dotenv \
       --with httpx --with "scikit-learn<1.6" --with "hdbscan==0.8.40" \
       scripts/build-knowledge-map.py

```

--------------------------------

### Create New Project

Source: https://bensevern.dev/docs/api/workbench

Creates a new project with a specified name, scope, and default trust level. The `default_trust` field is optional and defaults to 'gated'.

```json
{
  "name": "Q1 Customer Dedup",
  "scope_type": "workspace",
  "scope_id": "ws_01",
  "default_trust": "gated"
}

```

--------------------------------

### GET /api/golden/destinations/export

Source: https://bensevern.dev/docs/api/destinations

Streams a one-time download of all golden records for a specified entity type. This operation does not require a destination row or credentials.

```APIDOC
## GET /api/golden/destinations/export

### Description
Stream a one-shot download of every golden record for an `entity_type`. No destination row, no credentials.

### Method
GET

### Endpoint
`/api/golden/destinations/export`

### Parameters
#### Query Parameters
- **entity_type** (string) - Required - The entity type whose golden records should be exported.
- **format** (string) - Optional - The desired output format. Options: `csv` (default), `parquet`, or `excel`.
- **limit** (integer) - Optional - The maximum number of rows to return. Defaults to 100,000.

### Response
#### Success Response (200 OK)
Returns a file stream with `Content-Disposition: attachment` and the appropriate `Content-Type` based on the requested format:
  - `csv` → `text/csv`
  - `parquet` → `application/x-parquet`
  - `excel` → `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

### Errors
- **503 Service Unavailable**: Returned if the `excel` format is requested but the `xlsxwriter` library is not installed on the server.
```

--------------------------------

### Ingest Billing Source

Source: https://bensevern.dev/docs/guides/entity-resolution-workflow

Load the billing data source into the Golden Suite via the API. Each source gets its own namespace for traceability.

```bash
curl -X POST https://api.goldensuite.dev/v1/sources \
  -H "Authorization: Bearer $GOLDEN_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@billing_export.csv" \
  -F "name=billing" \
  -F "namespace=source_billing"

```

--------------------------------

### POST /api/demo/resample

Source: https://bensevern.dev/docs/api/demo

Re-run matching with different parameters on an existing demo session.

```APIDOC
## POST /api/demo/resample

### Description
Re-run matching with different parameters on an existing demo session.

### Method
POST

### Endpoint
/api/demo/resample

### Parameters
#### Request Body
- **session_id** (string) - Yes - Session ID from a previous upload
- **threshold** (number) - Yes - Match confidence threshold (0.0 - 1.0)
- **weights** (object) - Yes - Field-level weights for scoring

### Response
#### Success Response (200)
- **scored_pairs** (integer) - Description
- **cluster_count** (integer) - Description
- **execution_ms** (integer) - Description

#### Response Example
```json
{
  "scored_pairs": 342,
  "cluster_count": 87,
  "execution_ms": 1240
}
```

### Errors
- **404 Not Found**: Session ID not found or expired
- **422 Unprocessable Entity**: Invalid threshold or weights
```

--------------------------------

### Ingest CRM Source

Source: https://bensevern.dev/docs/guides/entity-resolution-workflow

Load the CRM data source into the Golden Suite via the API. Each source gets its own namespace for traceability.

```bash
curl -X POST https://api.goldensuite.dev/v1/sources \
  -H "Authorization: Bearer $GOLDEN_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@crm_export.csv" \
  -F "name=crm" \
  -F "namespace=source_crm"

```

--------------------------------

### List all projects

Source: https://bensevern.dev/docs/api/workbench

Retrieves a list of all projects accessible to the authenticated user. This endpoint provides an overview of existing projects, including their names, associated scopes, and creation details.

```APIDOC
## GET /api/workbench/projects

### Description
List all projects for the authenticated user.

### Method
GET

### Endpoint
/api/workbench/projects

### Response
#### Success Response
- **id** (string) - Unique identifier for the project
- **name** (string) - Display name of the project
- **scope_type** (string) - Type of the scope associated with the project
- **scope_id** (string) - ID of the scope associated with the project
- **default_trust** (string) - Default trust level for new notebooks
- **active_notebook_id** (string) - ID of the currently active notebook
- **created_at** (string) - Timestamp when the project was created

### Response Example
```json
[
  {
    "id": "proj_01",
    "name": "Q1 Customer Dedup",
    "scope_type": "workspace",
    "scope_id": "ws_01",
    "default_trust": "gated",
    "active_notebook_id": "nb_01",
    "created_at": "2026-04-01T09:00:00Z"
  }
]
```
```

--------------------------------

### Example Survivorship Rules Response

Source: https://bensevern.dev/docs/api/survivorship

Illustrates the structure of the response when retrieving survivorship rules. Each rule specifies a field, the strategy to apply, and its priority.

```json
[
  { "field": "name", "strategy": "most_recent", "priority": 1 },
  { "field": "email", "strategy": "most_complete", "priority": 2 },
  { "field": "phone", "strategy": "source_priority", "priority": 3 }
]
```

--------------------------------

### GET /api/demo/audit/quota

Source: https://bensevern.dev/docs/api/audit

Retrieve the caller's current daily quota usage for audits. This endpoint is useful for understanding rate limit consumption.

```APIDOC
## GET /api/demo/audit/quota

### Description
Return the caller's current daily quota usage.

### Method
GET

### Endpoint
/api/demo/audit/quota

### Response
#### Success Response (200)
- **limit** (integer) - The maximum number of audits allowed per day.
- **used** (integer) - The number of audits already used today.
- **resets_at** (string) - The timestamp when the quota resets.

### Response Example
```json
{
  "limit": 5,
  "used": 2,
  "resets_at": "2026-04-21T13:45:12+00:00"
}
```

**Note:** For anonymous callers, `limit` is `1` and `used` counts audits against the hashed IP. Quota windows are rolling 24 hours, not calendar days.
```

--------------------------------

### Sample BigQuery Query: Cross-Dataset Join

Source: https://bensevern.dev/docs/guides/integrations/bigquery

Demonstrates joining data from two different datasets within BigQuery, filtering out soft-deleted records.

```sql
-- Cross-dataset join
SELECT
    c.id, c.email, c.first_name, c.last_name,
    o.name AS company, o.industry,
    c.updated_at
FROM `prod.crm.customers` c
LEFT JOIN `prod.crm.organizations` o ON c.organization_id = o.id
WHERE c.deleted_at IS NULL;
```

--------------------------------

### GET /api/demo/audit/history

Source: https://bensevern.dev/docs/api/audit

Retrieve the signed-in user's past audits, ordered by creation date (newest first). Requires a Clerk Bearer token.

```APIDOC
## GET /api/demo/audit/history

### Description
Return the signed-in user's past audits, newest first. Requires Clerk Bearer token.

### Method
GET

### Endpoint
/api/demo/audit/history

### Response
#### Success Response (200)
- **audit_id** (string) - The unique identifier for the audit.
- **repo_url** (string) - The GitHub URL that was audited.
- **status** (string) - The status of the audit (e.g., `complete`).
- **entity_id** (string) - The unique identifier for the entity in the knowledge graph.
- **created_at** (string) - The timestamp when the audit was created.

### Response Example
```json
[
  {
    "audit_id": "3f2a7b8e-...",
    "repo_url": "https://github.com/owner/repo",
    "status": "complete",
    "entity_id": "repo-owner-repo",
    "created_at": "2026-04-20T13:45:12+00:00"
  }
]
```

**Note:** Returns up to 200 most recent audits for the authenticated user. Anonymous audits (submitted before signing in) aren't included — they're keyed to IP hash, not user ID.
```

--------------------------------

### POST /api/demo/upload

Source: https://bensevern.dev/docs/api/demo

Upload a file and run a Golden Suite tool against it. Returns a session ID for subsequent operations.

```APIDOC
## POST /api/demo/upload

### Description
Upload a file and run a Golden Suite tool against it. Returns a session ID for subsequent operations.

### Method
POST

### Endpoint
/api/demo/upload

### Parameters
#### Request Body
- **file** (file) - Yes - CSV or Excel file to process
- **tool** (string) - Yes - Tool name to run (e.g. `goldencheck`, `goldenmatch`)

### Response
#### Success Response (200)
- **session_id** (string) - Description
- **row_count** (integer) - Description
- **columns** (array) - Description

#### Response Example
```json
{
  "session_id": "abc123",
  "row_count": 1500,
  "columns": ["id", "name", "email", "phone"]
}
```

### Errors
- **413 Payload Too Large**: File exceeds the upload size limit
- **422 Unprocessable Entity**: Invalid file format or missing required field
```

--------------------------------

### Run Deduplication and Get Results

Source: https://bensevern.dev/docs/getting-started/quickstart

This snippet demonstrates how to deduplicate records from a CSV file and print the number of clusters found, total records, and ambiguous merges.

```python
import goldenmatch
result = goldenmatch.dedupe("customers.csv")
print(f"Found {result.cluster_count} clusters from {result.record_count} records")
print(f"Ambiguous (review-queue): {len(result.ambiguous_merges)}")
```

--------------------------------

### Sample BigQuery Query: Simple Table

Source: https://bensevern.dev/docs/guides/integrations/bigquery

A basic query to select specific columns from a partitioned table, filtering by the partition time to optimize performance and cost.

```sql
-- Simple table
SELECT id, email, first_name, last_name, phone, company, updated_at
FROM `your-project.analytics.customers`
WHERE _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY);
```