Rest Api

REST API

GoldenMatch includes a local HTTP server for real-time matching, cluster browsing, and data steward review.

Endpoints

Method	Path	Description
GET	/health	Health check
GET	/stats	Dataset statistics
POST	/match	Match a single record
POST	/match/batch	Match multiple records
POST	/explain	Explain why two records match
GET	/clusters	List all clusters
GET	/clusters/<id>	Get cluster detail
GET	/reviews	Review queue (borderline pairs)
GET	/reviews/decisions	List completed review decisions
POST	/reviews/decide	Approve or reject a pair

Stats

curl http://localhost:8080/stats

{
    "total_records": 5000,
    "total_clusters": 847,
    "singleton_count": 3200,
    "match_rate": 0.12,
    "avg_cluster_size": 2.1,
    "max_cluster_size": 8
}

Explain a match

curl -X POST http://localhost:8080/explain \
    -H "Content-Type: application/json" \
    -d '{"id_a": 42, "id_b": 108}'

{
    "overall_score": 0.92,
    "explanation": "Strong match: name similarity 0.88 (jaro_winkler), zip exact match.",
    "field_scores": [
        {"field": "name", "scorer": "jaro_winkler", "score": 0.88},
        {"field": "zip", "scorer": "exact", "score": 1.0}
    ]
}

Review queue

The review queue surfaces borderline pairs for data steward approval or rejection.

Get pending reviews

curl http://localhost:8080/reviews

{
    "reviews": [
        {
            "id": "rev_001",
            "id_a": 42,
            "id_b": 300,
            "score": 0.82,
            "record_a": {"name": "John Smith", "zip": "10001"},
            "record_b": {"name": "J. Smithson", "zip": "10001"}
        }
    ]
}

Make a decision

curl -X POST http://localhost:8080/reviews/decide \
    -H "Content-Type: application/json" \
    -d '{"id": "rev_001", "decision": "approve"}'

Decision values: "approve" or "reject".

List completed decisions

curl http://localhost:8080/reviews/decisions

Docker deployment

docker run --rm -p 8080:8080 -v $(pwd):/data \
    ghcr.io/benzsevern/goldenmatch:latest \
    serve --file /data/customers.csv --port 8080