StreetProof Physical Brand Index™ (PBI)

Developer documentation — REST API v1

Evidence-firstPrivacy-scrubbedMachine-readable

Add business-independent real-world evidence to an entity graph, search product, AI answer, risk model, or research workflow. The public REST API exposes accepted physical citations, Presence Records, PPS, city indexes, methodology receipts, and machine activity. The executable OpenAPI 3.1 contract is authoritative. Every example below is generated from one versioned fixture and checked against that contract during the production build.

Illustrative data only

Every record in this file is fictional and illustrative. Example identifiers never resolve to production records.

Lifecycle

API version: v1
Schema version: 2026-08-07.v11
Status: public_beta
Introduced: 2026-07-29
Canonical example artifact: /api-examples.json

The machine artifact and OpenAPI document include the exact deployed Git revision. They use the source revision and fixed fixture version, not a random generation timestamp.

Entity results are city-specific presence_record objects. The identity_hierarchy field publishes brand, organization, and scope relationships only after manual review. An unreviewed value means no relationship has been published; it never proves that none exists.

Access and invariants

Public read operations require no key during public beta.
Partner portal and webhook operations require a StreetProof bearer key.
No accepted StreetProof citation matched the request. It never proves absence, closure, inactivity, or that a business is unreal, regardless of coverage tier.
Entity records and evidence remain governed by the StreetProof Terms. Only aggregates expressly marked open are CC BY 4.0.

Evidence claim boundary

An accepted physical citation records that a brand or asset was observed at a documented time and privacy-safe place.

Ownership or control of an observed location or asset.
Licensing, legal status, legitimacy, quality, reputation, or continued operation.
Endorsement, affiliation, or customer sentiment.
Audience size, impressions, reach, conversions, sales, revenue, or return on investment.
A complete asset inventory, exhaustive city coverage, or absence when no matching citation exists.

Validated operation examples

All 20 OpenAPI operations are represented below. The same values are embedded into each operation in the OpenAPI document.

GET/api/v1/search

Search public Presence Records by name, city, or industry.

illustrative request

curl "https://streetproof.com/api/v1/search"

validated 200 application/json response

{
  "example_only": true,
  "query": {
    "name": "Northstar Bicycle Repair",
    "city": "example-city"
  },
  "coverage_status": "active",
  "coverage_message": "Illustrative city coverage.",
  "demand": null,
  "count": 1,
  "results": [
    {
      "public_id": "example_entity_001",
      "name": "Northstar Bicycle Repair",
      "city": "Example City",
      "industry": "bicycle-repair",
      "record_status": "active",
      "identity_status": "unclaimed",
      "status": "unclaimed",
      "is_synthetic": true,
      "pps": null,
      "provisional_pps": 42.5,
      "score_state": "provisional",
      "ranking_state": "insufficient_evidence",
      "ranking_reason": "Illustrative record has insufficient independent evidence.",
      "independent_observer_count": 1,
      "independent_observation_count": 1,
      "observation_day_count": 1,
      "ranking_gate": {
        "status": "evidence_building",
        "methodology_version": "2026-07-30.v3",
        "independent_observers": {
          "current": 1,
          "required": 3,
          "met": false
        },
        "countable_observations": {
          "current": 1,
          "required": 5,
          "met": false
        },
        "observation_days": {
          "current": 1,
          "required": 2,
          "met": false
        },
        "industry_classification": {
          "industry": "bicycle-repair",
          "state": "review",
          "method": "name_rule",
          "authoritative_for_ranking": false
        },
        "missing_requirements": [
          "independent_observers",
          "independent_observations",
          "observation_days",
          "industry_classification_review"
        ]
      },
      "first_observed": "2026-01-15T12:00:00Z",
      "last_observed": "2026-01-15T12:00:00Z",
      "record_url": "https://streetproof.com/entity/example_entity_001",
      "record_type": "presence_record",
      "identity_hierarchy": {
        "review_state": "reviewed",
        "scope": {
          "value": "local_independent",
          "review_state": "reviewed",
          "methodology_version": "entity-scope-v2"
        },
        "brand": {
          "public_id": "brand_example_001",
          "name": "Northstar Bicycle Repair",
          "canonical_domain": "northstar.example"
        },
        "organizations": [
          {
            "relationship_type": "operating_organization",
            "public_id": "org_example_001",
            "name": "Northstar Example Cooperative",
            "organization_type": "company",
            "canonical_domain": "northstar.example"
          }
        ],
        "note": "Only reviewed identity relationships are published."
      }
    }
  ],
  "methodology_url": "https://streetproof.com/methodology",
  "data_as_of": "2026-01-15T12:00:00Z"
}

GET/api/v1/entity/{public_id}

Read one public Presence Record, its assets, and current score state.

illustrative request

curl "https://streetproof.com/api/v1/entity/example_entity_001"

validated 200 application/json response

{
  "example_only": true,
  "entity": {
    "public_id": "example_entity_001",
    "name": "Northstar Bicycle Repair",
    "city": "Example City",
    "industry": "bicycle-repair",
    "record_status": "active",
    "identity_status": "unclaimed",
    "status": "unclaimed",
    "is_synthetic": true,
    "pps": null,
    "provisional_pps": 42.5,
    "score_state": "provisional",
    "ranking_state": "insufficient_evidence",
    "ranking_reason": "Illustrative record has insufficient independent evidence.",
    "independent_observer_count": 1,
    "independent_observation_count": 1,
    "observation_day_count": 1,
    "ranking_gate": {
      "status": "evidence_building",
      "methodology_version": "2026-07-30.v3",
      "independent_observers": {
        "current": 1,
        "required": 3,
        "met": false
      },
      "countable_observations": {
        "current": 1,
        "required": 5,
        "met": false
      },
      "observation_days": {
        "current": 1,
        "required": 2,
        "met": false
      },
      "industry_classification": {
        "industry": "bicycle-repair",
        "state": "review",
        "method": "name_rule",
        "authoritative_for_ranking": false
      },
      "missing_requirements": [
        "independent_observers",
        "independent_observations",
        "observation_days",
        "industry_classification_review"
      ]
    },
    "first_observed": "2026-01-15T12:00:00Z",
    "last_observed": "2026-01-15T12:00:00Z",
    "record_url": "https://streetproof.com/entity/example_entity_001",
    "website": "https://example.invalid",
    "same_as": [],
    "record_type": "presence_record",
    "identity_hierarchy": {
      "review_state": "reviewed",
      "scope": {
        "value": "local_independent",
        "review_state": "reviewed",
        "methodology_version": "entity-scope-v2"
      },
      "brand": {
        "public_id": "brand_example_001",
        "name": "Northstar Bicycle Repair",
        "canonical_domain": "northstar.example"
      },
      "organizations": [
        {
          "relationship_type": "operating_organization",
          "public_id": "org_example_001",
          "name": "Northstar Example Cooperative",
          "organization_type": "company",
          "canonical_domain": "northstar.example"
        }
      ],
      "note": "Only reviewed identity relationships are published."
    }
  },
  "presence_score": {
    "pps": null,
    "provisional_pps": 42.5,
    "score_state": "provisional",
    "ranking_state": "insufficient_evidence",
    "ranking_reason": "Illustrative record has insufficient independent evidence.",
    "independent_observer_count": 1,
    "independent_observation_count": 1,
    "observation_day_count": 1,
    "ranking_gate": {
      "status": "evidence_building",
      "methodology_version": "2026-07-30.v3",
      "independent_observers": {
        "current": 1,
        "required": 3,
        "met": false
      },
      "countable_observations": {
        "current": 1,
        "required": 5,
        "met": false
      },
      "observation_days": {
        "current": 1,
        "required": 2,
        "met": false
      },
      "industry_classification": {
        "industry": "bicycle-repair",
        "state": "review",
        "method": "name_rule",
        "authoritative_for_ranking": false
      },
      "missing_requirements": [
        "independent_observers",
        "independent_observations",
        "observation_days",
        "industry_classification_review"
      ]
    },
    "cohort_percentile": null,
    "pbi_rank": null,
    "pbi_cohort_size": null,
    "pbi_cohort": null,
    "rank_tie_policy": "dense_rank_on_full_precision_pps"
  },
  "stats": {
    "observation_count": 1,
    "unique_assets": 1,
    "unique_cells": 1
  },
  "assets": []
}

GET/api/v1/entity/{public_id}/evidence

Read the citable public evidence packet for one Presence Record.

illustrative request

curl "https://streetproof.com/api/v1/entity/example_entity_001/evidence"

validated 200 application/json response

{
  "schema": "com.streetproof.public_evidence_packet.v2",
  "generated_at": "2026-01-15T12:00:00Z",
  "example_only": true,
  "record": {
    "public_id": "example_entity_001",
    "name": "Northstar Bicycle Repair",
    "city": "example-city",
    "city_name": "Example City",
    "industry": "bicycle-repair",
    "record_status": "active",
    "identity_status": "unclaimed",
    "status": "unclaimed",
    "is_synthetic": true,
    "first_observed": "2026-01-15T12:00:00Z",
    "last_observed": "2026-01-15T12:00:00Z",
    "urls": {
      "record": "https://streetproof.com/entity/example_entity_001"
    }
  },
  "what_this_proves": [
    "An accepted physical citation records that a brand or asset was observed at a documented time and privacy-safe place.",
    "The citation's presence_kind states whether it supports location_presence, mobile_presence, or brand_mention."
  ],
  "what_this_does_not_prove": [
    "Ownership or control of an observed location or asset.",
    "Licensing, legal status, legitimacy, quality, reputation, or continued operation.",
    "Endorsement, affiliation, or customer sentiment.",
    "Audience size, impressions, reach, conversions, sales, revenue, or return on investment.",
    "A complete asset inventory, exhaustive city coverage, or absence when no matching citation exists."
  ],
  "evidence_claim_boundary": {
    "schema": "com.streetproof.evidence_claim_boundary.v1",
    "contract_version": "2026-07-30.v1",
    "positive_result": {
      "summary": "An accepted physical citation records that a brand or asset was observed at a documented time and privacy-safe place.",
      "presence_kinds": {
        "location_presence": "A matched fixed-location asset was observed at that place. This does not establish ownership, tenancy, licensing, or continued operation.",
        "mobile_presence": "A matched branded mobile asset was observed. This does not establish its owner, home base, operating address, or route.",
        "brand_mention": "Branding was visible in the observation. This does not establish ownership, operation, affiliation, or endorsement at that place."
      }
    },
    "no_result": {
      "meaning": "No accepted StreetProof citation matched the request.",
      "limitation": "It never proves absence, closure, inactivity, or that a business is unreal, regardless of coverage tier."
    },
    "what_this_proves": [
      "An accepted physical citation records that a brand or asset was observed at a documented time and privacy-safe place.",
      "The citation's presence_kind states whether it supports location_presence, mobile_presence, or brand_mention."
    ],
    "what_this_does_not_prove": [
      "Ownership or control of an observed location or asset.",
      "Licensing, legal status, legitimacy, quality, reputation, or continued operation.",
      "Endorsement, affiliation, or customer sentiment.",
      "Audience size, impressions, reach, conversions, sales, revenue, or return on investment.",
      "A complete asset inventory, exhaustive city coverage, or absence when no matching citation exists."
    ]
  },
  "observations": {
    "total_public": 1,
    "unique_assets": 1,
    "unique_cells": 1,
    "source_mix": [],
    "verification_mix": [],
    "presence_mix": [],
    "recent": []
  },
  "assets": [],
  "citations": {}
}

GET/api/v1/presence-score/{public_id}

Read PPS, eligibility, cohort context, and score history.

illustrative request

curl "https://streetproof.com/api/v1/presence-score/example_entity_001"

validated 200 application/json response

{
  "example_only": true,
  "public_id": "example_entity_001",
  "name": "Northstar Bicycle Repair",
  "is_synthetic": true,
  "pps": null,
  "provisional_pps": 42.5,
  "score_state": "provisional",
  "ranking_state": "insufficient_evidence",
  "ranking_reason": "Illustrative record has insufficient independent evidence.",
  "independent_observer_count": 1,
  "independent_observation_count": 1,
  "observation_day_count": 1,
  "ranking_gate": {
    "status": "evidence_building",
    "methodology_version": "2026-07-30.v3",
    "independent_observers": {
      "current": 1,
      "required": 3,
      "met": false
    },
    "countable_observations": {
      "current": 1,
      "required": 5,
      "met": false
    },
    "observation_days": {
      "current": 1,
      "required": 2,
      "met": false
    },
    "industry_classification": {
      "industry": "bicycle-repair",
      "state": "review",
      "method": "name_rule",
      "authoritative_for_ranking": false
    },
    "missing_requirements": [
      "independent_observers",
      "independent_observations",
      "observation_days",
      "industry_classification_review"
    ]
  },
  "components": null,
  "cohort_percentile": null,
  "cohort": {},
  "pbi_rank": null,
  "pbi_cohort_size": null,
  "rank_tie_policy": "dense_rank_on_full_precision_pps",
  "history": []
}

GET/api/v1/observations/{public_id}

Read bounded public physical-citation ledger rows.

illustrative request

curl "https://streetproof.com/api/v1/observations/example_entity_001"

validated 200 application/json response

{
  "example_only": true,
  "public_id": "example_entity_001",
  "is_synthetic": true,
  "count": 1,
  "note": "Illustrative physical citation.",
  "observations": [
    {
      "id": 1001,
      "asset_id": 2001,
      "source_type": "scout",
      "observed_at": "2026-01-15T12:00:00Z",
      "accepted_at": "2026-01-15T12:05:00Z",
      "published_at": "2026-01-15T12:06:00Z",
      "reprocessed_at": null,
      "derived_from_archive": false,
      "recognition_model_version": null,
      "methodology_version": "example-methodology-v1",
      "h3_cell": "example-cell",
      "observation_verification_state": "corroborated",
      "verif_state": "corroborated",
      "city": "Example City",
      "region": "Example Region",
      "country": "CA",
      "presence_kind": "location_presence",
      "physical_citation": true,
      "ledger_schema_version": 2,
      "trust_weight": 1,
      "ledger_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

GET/api/v1/city/{city}/index

Page through a frozen city snapshot with official, evidence-building, and integrity-review states.

illustrative request

curl "https://streetproof.com/api/v1/city/example-city/index"

validated 200 application/json response

{
  "example_only": true,
  "city": {
    "slug": "example-city",
    "name": "Example City",
    "region": "Example Region",
    "region_code": "01",
    "country": "CA",
    "country_name": "Canada",
    "geoname_id": 9999999,
    "display_label": "Example City, Example Region, Canada",
    "publication_status": "published",
    "collection_status": "active",
    "public_index_url": "/index/example-city",
    "launched": true
  },
  "launch_status": "launched",
  "coverage_status_deprecated": true,
  "coverage_status": "active",
  "coverage_message": "Illustrative city coverage.",
  "demand": null,
  "data_available": true,
  "industry": null,
  "ranking_state": null,
  "claim_status": null,
  "license": "StreetProof Terms; open aggregates are CC BY 4.0.",
  "returned_count": 1,
  "total_count": 1,
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "snapshot_id": "00000000-0000-4000-8000-000000000001",
  "ranking_summary": {
    "eligible": 0,
    "evidence_building": 1,
    "integrity_review": 0
  },
  "rankings": [
    {
      "public_id": "example_entity_001",
      "name": "Northstar Bicycle Repair",
      "city": "Example City",
      "industry": "bicycle-repair",
      "record_status": "active",
      "identity_status": "unclaimed",
      "status": "unclaimed",
      "is_synthetic": true,
      "pps": null,
      "provisional_pps": 42.5,
      "score_state": "provisional",
      "ranking_state": "insufficient_evidence",
      "ranking_reason": "Illustrative record has insufficient independent evidence.",
      "independent_observer_count": 1,
      "independent_observation_count": 1,
      "observation_day_count": 1,
      "ranking_gate": {
        "status": "evidence_building",
        "methodology_version": "2026-07-30.v3",
        "independent_observers": {
          "current": 1,
          "required": 3,
          "met": false
        },
        "countable_observations": {
          "current": 1,
          "required": 5,
          "met": false
        },
        "observation_days": {
          "current": 1,
          "required": 2,
          "met": false
        },
        "industry_classification": {
          "industry": "bicycle-repair",
          "state": "review",
          "method": "name_rule",
          "authoritative_for_ranking": false
        },
        "missing_requirements": [
          "independent_observers",
          "independent_observations",
          "observation_days",
          "industry_classification_review"
        ]
      },
      "first_observed": "2026-01-15T12:00:00Z",
      "last_observed": "2026-01-15T12:00:00Z",
      "record_url": "https://streetproof.com/entity/example_entity_001",
      "rank": null,
      "rank_tie_policy": "dense_rank_on_full_precision_pps",
      "record_type": "presence_record",
      "identity_hierarchy": {
        "review_state": "reviewed",
        "scope": {
          "value": "local_independent",
          "review_state": "reviewed",
          "methodology_version": "entity-scope-v2"
        },
        "brand": {
          "public_id": "brand_example_001",
          "name": "Northstar Bicycle Repair",
          "canonical_domain": "northstar.example"
        },
        "organizations": [
          {
            "relationship_type": "operating_organization",
            "public_id": "org_example_001",
            "name": "Northstar Example Cooperative",
            "organization_type": "company",
            "canonical_domain": "northstar.example"
          }
        ],
        "note": "Only reviewed identity relationships are published."
      }
    }
  ],
  "data_as_of": "2026-01-15T12:00:00Z",
  "methodology_url": "https://streetproof.com/methodology"
}

GET/api/v1/coverage-status/{city}

Read a known city’s launch and coverage state.

illustrative request

curl "https://streetproof.com/api/v1/coverage-status/example-city"

validated 200 application/json response

{
  "example_only": true,
  "requested_city": "example-city",
  "status": "active",
  "data_available": true,
  "message": "Illustrative coverage state.",
  "city": {
    "slug": "example-city",
    "name": "Example City"
  },
  "coverage": {
    "tier": "building",
    "label": "Building coverage",
    "freshness": "current",
    "confidence": "medium",
    "methodology_version": "city-coverage-v3",
    "tier_since": "2026-01-01",
    "calculated_at": "2026-01-15T12:00:00Z",
    "snapshot_id": "11111111-1111-4111-8111-111111111111",
    "coverage_basis": "eligible_cell_ratio",
    "eligible_cell_manifest_id": "22222222-2222-4222-8222-222222222222",
    "denominator_status": "reviewed",
    "limitations": "Positive evidence is useful, but missing evidence remains inconclusive.",
    "metrics": {
      "physical_citations_180d": 518,
      "unique_entities_180d": 362,
      "unique_assets_180d": 140,
      "observed_cells_90d": 41,
      "observed_eligible_cells_90d": 36,
      "eligible_coverage_cells": 6348,
      "cell_coverage_ratio_90d": 0.00567,
      "independent_scout_observers_180d": 1,
      "independent_scout_observations_180d": 18,
      "independent_scout_days_180d": 7,
      "repeat_entity_rate_180d": 0.12,
      "active_observation_days_30d": 12,
      "fresh_cell_rate_45d": 0.8,
      "source_family_count_180d": 4,
      "largest_source_family_share_180d": 0.7
    },
    "dense_gate": {
      "eligible": false,
      "available": true,
      "pass_streak_days": 0,
      "required_stability_days": 7,
      "requirements": [
        {
          "key": "reviewed_denominator",
          "met": true,
          "current": "reviewed",
          "required": "reviewed"
        },
        {
          "key": "eligible_cell_coverage",
          "met": false,
          "current": 0.00567,
          "required": 0.3
        },
        {
          "key": "independent_scouts",
          "met": false,
          "current": 1,
          "required": 3
        }
      ],
      "missing_requirements": [
        "eligible_cell_coverage",
        "independent_scouts"
      ]
    }
  },
  "demand": null,
  "available_cities": []
}

GET/api/v1/explorer.csv

Export the bounded aggregate Explorer dataset as CSV.

illustrative request

curl "https://streetproof.com/api/v1/explorer.csv"

validated 200 text/csv response

city,industry,asset_type,claim_state,entities,observations,observed_cells,coverage_level,assets,avg_pps,avg_percentile,first_observed,last_observed
Example City,bicycle-repair,storefront,unclaimed,1,1,1,low,1,,,,

GET/api/v1/locations/cities

Search the independent GeoNames city catalogue.

illustrative request

curl "https://streetproof.com/api/v1/locations/cities"

validated 200 application/json response

{
  "schema": "com.streetproof.geonames_city_options.v1",
  "source": "GeoNames cities500",
  "country": "CA",
  "query": "Example",
  "example_only": true,
  "cities": [
    {
      "geonameId": 9999999,
      "name": "Example City",
      "asciiName": "Example City",
      "region": "Example Region",
      "countryCode": "CA",
      "countryName": "Canada",
      "population": 123456
    }
  ]
}

GET/api/v1/taxonomy/industries

Search the UN ISIC Revision 5 taxonomy.

illustrative request

curl "https://streetproof.com/api/v1/taxonomy/industries"

validated 200 application/json response

{
  "schema": "com.streetproof.isic_industry_options.v1",
  "source": "United Nations ISIC Revision 5",
  "query": "repair",
  "example_only": true,
  "industries": [
    {
      "code": "9529",
      "title": "Repair and maintenance of other personal and household goods",
      "level": "class",
      "sectionCode": "T",
      "sectionTitle": "Other service activities"
    }
  ]
}

GET/api/v1/cities

List StreetProof cities with versioned coverage context.

illustrative request

curl "https://streetproof.com/api/v1/cities"

validated 200 application/json response

[
  {
    "id": 9999999,
    "slug": "example-city",
    "name": "Example City",
    "region": "Example Region",
    "region_code": "01",
    "country": "CA",
    "country_name": "Canada",
    "geoname_id": 9999999,
    "display_label": "Example City, Example Region, Canada",
    "publication_status": "published",
    "collection_status": "active",
    "data_available": true,
    "public_index_url": "/index/example-city",
    "launched": true,
    "coverage": {
      "level": "low",
      "tier": "seed",
      "freshness": "current",
      "observed_cells": 1,
      "methodology_version": "city-coverage-v3",
      "calculated_at": "2026-01-15T12:00:00Z",
      "limitations": "Illustrative fixture.",
      "note": "Illustrative fixture."
    }
  }
]

GET/api/v1/methodology/metrics

Read the public methodology-quality report.

illustrative request

curl "https://streetproof.com/api/v1/methodology/metrics"

validated 200 application/json response

{
  "schema": "com.streetproof.public_methodology_metrics.v1",
  "generated_at": "2026-01-15T12:00:00Z",
  "example_only": true,
  "reporting_window": {},
  "urls": {},
  "summary": {
    "verified_observations": 0,
    "strictly_verified_observations": 0
  },
  "deprecated_fields": {},
  "headline_metrics": [],
  "ocr_sample": {},
  "entity_match_sample": {},
  "dispute_metrics": {},
  "coverage_by_city": [],
  "limitations": [
    "Illustrative fixture; not a production metric."
  ]
}

GET/api/v1/search-ai-readiness

Read machine-discovery and interface readiness.

illustrative request

curl "https://streetproof.com/api/v1/search-ai-readiness"

validated 200 application/json response

{
  "schema": "com.streetproof.search_ai_readiness.v1",
  "generated_at": "2026-01-15T12:00:00Z",
  "status": "public_beta",
  "canonical_url": "https://streetproof.com/search-ai-readiness",
  "machine_json_url": "https://streetproof.com/api/v1/search-ai-readiness",
  "example_only": true,
  "summary": {
    "metrics_available": false,
    "metrics_status": "unavailable",
    "public_entities": null,
    "public_observations": null,
    "public_assets": null,
    "cities_with_production_evidence": null,
    "synthetic_entities": null,
    "latest_public_observation_at": null,
    "coverage_is_city_specific": true,
    "city_distribution": null,
    "freshness_distribution": null
  },
  "surfaces": [],
  "access_policy": {},
  "freshness": {},
  "usage_visibility": {},
  "limitations": [
    "Illustrative fixture; not a production metric."
  ],
  "recommended_citations": {}
}

GET/api/v1/machine-activity

Read privacy-minimized REST, MCP, and crawler activity.

illustrative request

curl "https://streetproof.com/api/v1/machine-activity"

validated 200 application/json response

{
  "schema": "com.streetproof.machine_activity.v2",
  "generated_at": "2026-01-15T12:00:00Z",
  "window_start": "2026-01-08T12:00:00Z",
  "window_end": "2026-01-15T12:00:00Z",
  "window_days": 7,
  "raw_event_retention_days": 90,
  "aggregate_retention": "indefinite",
  "example_only": true,
  "counts": {
    "external_requests": 0,
    "excluded_internal_requests": 0,
    "external_daily_client_instances": 0,
    "attributed_recurring_clients": 0,
    "transport": {
      "rest_requests": 0,
      "mcp_requests": 0,
      "other_machine_requests": 0
    },
    "client_class": {
      "search_crawler_requests": 0,
      "ai_crawler_requests": 0,
      "authenticated_partner_requests": 0,
      "anonymous_or_unattributed_requests": 0,
      "other_client_requests": 0
    },
    "response_status": {
      "status_2xx": 0,
      "status_3xx": 0,
      "status_4xx": 0,
      "status_5xx": 0,
      "unclassified": 0
    },
    "timeout_requests": 0,
    "schema_validation_failures": 0,
    "rate_limited_requests": 0
  },
  "latest_external_request_at": null,
  "week_over_week": {},
  "traffic_classes": [],
  "attribution_confidence": [],
  "top_endpoints": [],
  "top_mcp_tools": [],
  "most_queried_cities": [],
  "most_queried_entities": [],
  "daily": [],
  "note": "Illustrative fixture; not production traffic."
}

GET/api/v1/pulse/{city}

Read the StreetPulse change feed for one city.

illustrative request

curl "https://streetproof.com/api/v1/pulse/example-city"

validated 200 application/json response

{
  "schema": "com.streetproof.streetpulse_city_feed.v1",
  "example_only": true,
  "city": {
    "slug": "example-city",
    "name": "Example City"
  },
  "since": "2026-01-01T00:00:00Z",
  "status": "active",
  "summary": {},
  "feeds": {},
  "webhook_contract": {},
  "unavailable_event_classes": [],
  "events": [
    {
      "id": "example_event_001",
      "type": "new_public_record",
      "detected_at": "2026-01-15T12:00:00Z",
      "headline": "Illustrative new Presence Record",
      "summary": "Northstar Bicycle Repair is a fictional example.",
      "entity_public_id": "example_entity_001",
      "entity_name": "Northstar Bicycle Repair",
      "record_url": "https://streetproof.com/entity/example_entity_001",
      "industry": "bicycle-repair",
      "asset_public_id": "example_asset_001",
      "asset_type": "storefront",
      "corridor": null,
      "confidence": 0.95,
      "confidence_label": "ledger",
      "evidence_count": 1
    }
  ]
}

GET/api/v1/status

getPublicSystemStatus

illustrative request

curl "https://streetproof.com/api/v1/status"

validated 200 application/json response

{
  "schema": "com.streetproof.public_status.v1",
  "snapshot_id": "00000000-0000-4000-8000-000000000001",
  "data_as_of": "2026-01-15T12:00:00Z",
  "metric_scope": "production_non_synthetic",
  "snapshot_type": "live_ledger",
  "current_status": "operational",
  "processing": {
    "latest_live_ledger_row": 1001,
    "latest_live_ledger_at": "2026-01-15T12:00:00Z",
    "latest_externally_sealed_row": 1000,
    "latest_external_seal_at": "2026-01-15T11:55:00Z",
    "rows_awaiting_next_checkpoint": 1,
    "next_checkpoint_time": "2026-01-16T00:00:00Z"
  },
  "incidents": [],
  "example_only": true
}

POST/api/v1/alerts/subscribe

Create or update a pending StreetPulse alert subscription.

illustrative request

curl -X POST "https://streetproof.com/api/v1/alerts/subscribe"   -H 'content-type: application/json'   -d '{"email":"[email protected]","city":"example-city","channel":"email"}'

validated 201 application/json response

{
  "schema": "com.streetproof.alert_subscription.v1",
  "ok": true,
  "example_only": true,
  "subscription": {
    "public_id": "example_subscription_001",
    "status": "pending",
    "created": true,
    "channel": "email",
    "scope": {
      "city": "example-city"
    },
    "event_types": [
      "new_public_record"
    ],
    "min_confidence": 0.6
  },
  "delivery": {
    "status": "verification_pending",
    "queued_events": 0,
    "note": "Illustrative fixture."
  },
  "preview": {
    "matched_events": 0,
    "latest_events": []
  }
}

GET/api/v1/ledger-checkpoints

Read signed ledger checkpoints and external proof status.

illustrative request

curl "https://streetproof.com/api/v1/ledger-checkpoints"

validated 200 application/json response

{
  "external_timestamping_active": true,
  "externally_confirmed": true,
  "anchor_repository": "https://github.com/gdf-labs/streetproof-ledger-anchors",
  "example_only": true,
  "checkpoints": [
    {
      "date": "2026-01-15",
      "environment": "production",
      "checkpoint_type": "daily",
      "first_observation_id": 1001,
      "last_observation_id": 1001,
      "leaf_count": 1,
      "merkle_root": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "last_ledger_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "previous_manifest_sha256": null,
      "manifest_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "hash_algorithm": "sha256",
      "canonicalization_version": "streetproof-checkpoint-json-v1",
      "created_at": "2026-01-15T23:59:00Z",
      "signing_key_id": "example-key",
      "external_proof": {
        "provider": "OpenTimestamps",
        "status": "confirmed",
        "proof_sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
        "verified_at": "2026-01-16T12:00:00Z"
      }
    }
  ]
}

GET/api/v1/partner/portal

Read the authenticated partner integration payload.

illustrative request

curl "https://streetproof.com/api/v1/partner/portal"

validated 200 application/json response

{
  "schema": "com.streetproof.partner_portal.v1",
  "example_only": true,
  "client": {
    "name": "Example Integration"
  },
  "quota": {
    "daily": 1000,
    "monthly": 10000,
    "used_today": 0,
    "used_this_month": 0,
    "daily_remaining": 1000,
    "monthly_remaining": 10000
  },
  "usage": {
    "requests_7d": 0,
    "errors_24h": 0,
    "p95_latency_ms_24h": null,
    "endpoint_mix_30d": [],
    "recent_requests": []
  },
  "api_keys": [],
  "webhooks": {},
  "integrations": {},
  "attribution": {}
}

POST/api/v1/partner/webhooks

Create or rotate an authenticated partner webhook.

illustrative request

curl -X POST "https://streetproof.com/api/v1/partner/webhooks"   -H 'content-type: application/json'   -d '{"endpoint_url":"https://example.invalid/streetproof-webhook","event_types":["new_public_record"],"city":"example-city"}'

validated 201 application/json response

{
  "schema": "com.streetproof.partner_webhook.v1",
  "ok": true,
  "example_only": true,
  "webhook": {
    "public_id": "example_webhook_001",
    "endpoint_url": "https://example.invalid/streetproof-webhook",
    "status": "pending"
  },
  "signing_secret": "example-secret-shown-once",
  "note": "Illustrative fixture; never use this secret."
}

Shared error examples

{
  "400": {
    "error": "Example invalid parameter.",
    "example_only": true
  },
  "404": {
    "error": "Example resource not found.",
    "example_only": true
  },
  "409": {
    "error": "Example request conflicts with the current resource state.",
    "example_only": true
  },
  "410": {
    "error": "Example snapshot expired. Restart the request.",
    "example_only": true
  },
  "429": {
    "error": "Example request rate exceeded. Retry later.",
    "example_only": true
  }
}

Other machine formats

StreetPulse also publishes RSS at /pulse/{city}/rss.xml. The build parses the canonical RSS fixture as XML and checks the CSV example’s exact header and row width.

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"><channel><title>StreetProof Example City</title><link>https://streetproof.com/pulse/example-city</link><description>Fictional illustrative StreetPulse feed.</description><item><guid>example_event_001</guid><title>Illustrative new Presence Record</title><link>https://streetproof.com/entity/example_entity_001</link><pubDate>Thu, 15 Jan 2026 12:00:00 GMT</pubDate></item></channel></rss>

MCP

Prefer typed tools? The public MCP server publishes the same fixture version, validated tool results, and output schemas.