REST API reference Live, enriched data on US local businesses. Version 1.0.0. Download the OpenAPI 3.1 spec .
Aggregates are free and never return names, IDs or coordinates. Record-level endpoints bill prepaid credits: 3 credits ($0.03) per standard record, 10 credits ($0.10) per hot record (new or changed in the last 30 days), charged once per unique record per calendar month. Paid responses include `credits_used` and `balance_remaining`. Over-rate requests answer 429 with `{"error":"slow_down","retry_after":N}`.
Conventions Base URL https://opsblu.com. All paths are under /v1. JSON in, JSON out (exports download CSV). Auth: Authorization: Bearer ob_live_…. Endpoints marked public need no credential. Slugs are lowercase-hyphenated: oregon, portland, hvac-contractors. GET /v1/categories is the vocabulary. Booleans in query strings accept true/false or 1/0. Aggregate counts under 5 are the string "<5" (type Count ). Treat it as "some, fewer than five". Timestamps are RFC 3339 UTC. Try it : free endpoints work in your terminal right now. For paid endpoints, create a key at /app/api-keys ; your first key adds 750 free credits.
Aggregates Free. Counts only, small counts rendered as "<5".
GET /v1/coverage public Collection-wide counters and covered cities
Responses curl bash curl \
"https://opsblu.com/v1/coverage" GET /v1/stats public Aggregate stats for a state, city or city × category
Parameters Name In Type Description state query string city query string category query string
Responses Code Description Body 200 OK Stats 404 Not found Error
curl bash curl \
"https://opsblu.com/v1/stats?state=oregon&city=portland&category=dentists" GET /v1/stats/history public Per-day crawl counters for one state (live data only)
One point per day from the crawl ledger, oldest first. Answers 503 live_data_unavailable when the API is running on fixtures or the ScyllaDB cluster is unreachable.
Parameters Name In Type Description staterequired query string Two-letter code or slug (OR, oregon) days query integerdefault 30
Responses curl bash curl \
"https://opsblu.com/v1/stats/history?state=OR&days=" POST /v1/stats/polygon public Aggregate stats inside a drawn boundary
The polygon is snapped to H3 cells server-side. Minimum area ~0.5 km². Hex counts under 5 come back as "<5".
Request body application/json, required Field Type Description geojsonrequired object categories string[] persona "web" | "seo" | "ppc" | "opening"
Responses Code Description Body 200 OK Stats
curl bash curl -X POST \
-H "Content-Type: application/json" -d '{"geojson":{},"categories":[],"persona":"web"}' \
"https://opsblu.com/v1/stats/polygon" GET /v1/categories public Controlled category vocabulary with national counts
Parameters Name In Type Description state query string With live data: the scraper's category terms for one state from leads.category_stats (slugified, counts <5 suppressed), with source: "live". Otherwise, or when the table is absent, the fixture vocabulary.
Responses Code Description Body 200 OK object
curl bash curl \
"https://opsblu.com/v1/categories?state=OR" Businesses Search is free (names + signals). Opening a record bills credits.
GET /v1/businesses Search businesses (free: names + signals, no contacts)
Parameters Name In Type Description state query string city query string zip query string category query string q query string Name contains no_website query boolean cwv_fail query boolean platform query "wordpress" | "wix" | "squarespace" | "shopify" | "other" has_ads query boolean has_analytics query boolean server_side query boolean new_days query integer changed_days query integer has_phone query boolean has_email query boolean hot query boolean cursor query string limit query integerdefault 25
Responses Code Description Body 200 OK BusinessPage 429 Rate limited. Back off for retry_after seconds. Error
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/businesses?state=oregon&city=portland&zip=97201" GET /v1/businesses/{id} Open a full record (billed once per month)
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 OK object 401 Sign in or pass an API key Error 402 Insufficient credits or spend cap reached Error 404 Not found Error
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/businesses/ob_por_den_0007" Changes What changed in a territory since a timestamp.
GET /v1/changes Change events since a timestamp
Parameters Name In Type Description since query string (date-time) Default: 7 days ago territory_id query string types query string Comma list: new_business, site_launched, platform_changed, pixel_added, pixel_removed, closed state query string city query string category query string limit query integerdefault 200
Responses Code Description Body 200 OK object
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/changes?since=2026-10-21T00:00:00Z&territory_id=ter_3a…&types=new_business" Exports Two-step: create (estimate) then confirm (charge).
GET /v1/exports List exports
Responses Code Description Body 200 OK object
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/exports" POST /v1/exports Create an export and get a credit estimate (nothing charged yet)
Request body application/json, required Field Type Description filters Filters ids string[]
Responses Code Description Body 201 Created, status pending_confirm Export
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"filters":{},"ids":[]}' \
"https://opsblu.com/v1/exports" GET /v1/exports/{id} Get an export
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 OK Export
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/exports/ob_por_den_0007" POST /v1/exports/{id}/confirm Confirm and charge; makes the CSV available
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 Ready Export 402 Insufficient credits or spend cap reached Error
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/exports/ob_por_den_0007/confirm" GET /v1/exports/{id}/download Download CSV
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 CSV text/csv
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/exports/ob_por_den_0007/download" Report card, removal requests, sample pages.
POST /v1/report-card public Score a business website
Request body application/json, required Field Type Description url string business string city string
Responses Code Description Body 201 Created object
curl bash curl -X POST \
-H "Content-Type: application/json" -d '{"url":"https://example.com","business":"","city":"portland"}' \
"https://opsblu.com/v1/report-card" GET /v1/report-card/{id} public Get a report card
Parameters Name In Type Description idrequired path string
Responses curl bash curl \
"https://opsblu.com/v1/report-card/ob_por_den_0007" POST /v1/removal-requests public Ask us to remove a business
Request body application/json, required Field Type Description business_namerequired string domain string address string requester_emailrequired string (email) relationship "owner" | "employee" | "other"
Responses curl bash curl -X POST \
-H "Content-Type: application/json" -d '{"business_name":"Alder Street Dental","domain":"example.com","address":"","requester_email":"owner@example.com"}' \
"https://opsblu.com/v1/removal-requests" GET /v1/samples/{token} public Outreach sample page payload (noindex)
Parameters Name In Type Description tokenrequired path string
Responses Code Description Body 200 OK 410 Expired
curl bash curl \
"https://opsblu.com/v1/samples/demo" Account Credits, billing, keys, territories.
GET /v1/me Current account and balance
Responses curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/me" POST /v1/me/connect-bonus Claim the +750 connect bonus (MCP/API/TagFrog)
Request body application/json Field Type Description source "mcp" | "api" | "tagfrog"
Responses Code Description Body 200 OK Account 409 Already granted
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"source":"mcp"}' \
"https://opsblu.com/v1/me/connect-bonus" POST /v1/billing/topup Start a Stripe Checkout top-up
Request body application/json, required Field Type Description amountrequired number
Responses Code Description Body 200 OK object
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"amount":20}' \
"https://opsblu.com/v1/billing/topup" PUT /v1/billing/spend-cap Set the monthly spend cap
Request body application/json, required Field Type Description monthly_usd number
Responses curl bash curl -X PUT -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"monthly_usd":20}' \
"https://opsblu.com/v1/billing/spend-cap" GET /v1/billing/ledger Credit ledger
Responses Code Description Body 200 OK object
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/billing/ledger" GET /v1/keys List keys
Responses Code Description Body 200 OK
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/keys" POST /v1/keys Create an API key (secret shown once)
Request body application/json Field Type Description label string spend_cap number
Responses Code Description Body 201 Created APIKey
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"label":"claude-desktop","spend_cap":20}' \
"https://opsblu.com/v1/keys" DELETE /v1/keys/{id} Revoke a key
Parameters Name In Type Description idrequired path string
Responses Code Description Body 204 Revoked
curl bash curl -X DELETE -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/keys/ob_por_den_0007" GET /v1/territories List territories
Responses Code Description Body 200 OK
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/territories" POST /v1/territories Save a territory
Request body application/json, required Field Type Description id string name string kind "city" | "zip" | "polygon" state string city string zip string geojson object alerts object
Responses Code Description Body 201 Created
curl bash curl -X POST -H "Authorization: Bearer ob_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"id":"","name":"Portland metro","kind":"city","state":"oregon"}' \
"https://opsblu.com/v1/territories" GET /v1/territories/{id} Get a territory
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 OK
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/territories/ob_por_den_0007" PUT /v1/territories/{id} Update a territory / alerts
Parameters Name In Type Description idrequired path string
Responses Code Description Body 200 OK
curl bash curl -X PUT -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/territories/ob_por_den_0007" DELETE /v1/territories/{id} Delete a territory
Parameters Name In Type Description idrequired path string
Responses Code Description Body 204 Deleted
curl bash curl -X DELETE -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/territories/ob_por_den_0007" Technology Infrasight technology intelligence. Counts are free; lists of domains and change feeds bill 3 credits per domain, once per domain per calendar month.
GET /v1/tech public Technology index (free): every technology with sites, added_30d, removed_30d
Parameters Name In Type Description q query string Name contains limit query integer
Responses Code Description Body 200 OK object 429 Rate limited. Back off for retry_after seconds. Error 503 Technology data unavailable (cluster down or tables not created yet) Error
curl bash curl \
"https://opsblu.com/v1/tech?q=dental&limit=25" GET /v1/tech/{technology} public One technology (free): counts + sites by state, suppressed under 5
Parameters Name In Type Description technologyrequired path string Name or slug
Responses Code Description Body 200 OK TechDetail 404 Not found Error 429 Rate limited. Back off for retry_after seconds. Error 503 Technology data unavailable (cluster down or tables not created yet) Error
curl bash curl \
"https://opsblu.com/v1/tech/<technology>" GET /v1/tech/{technology}/sites Domains running a technology (paid: 3 credits per domain, once per domain per month)
Each domain returned is a record and goes through the same reveal path as GET /v1/businesses/{id}: 3 credits ($0.03), billed once per domain per calendar month, free to re-open. Anonymous callers get the counts and the price with a 402. Removal tickets suppress a domain here immediately.
Parameters Name In Type Description technologyrequired path string Name or slug state query string Two-letter state city query string limit query integerdefault 25 cursor query string next_cursor from the previous page
Responses Code Description Body 200 OK TechSitePage 402 Unpaid: counts and the price, never domains Error 404 Not found Error 429 Rate limited. Back off for retry_after seconds. Error 503 Technology data unavailable (cluster down or tables not created yet) Error
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/tech/<technology>/sites?state=OR&city=portland&limit=25" GET /v1/tech/{technology}/changes Domains that added / removed / re-versioned a technology since a date (paid per domain)
One row per change, newest day first, window capped at 90 days. A domain that changed twice is one record (billed once). Same billing as /sites.
Parameters Name In Type Description technologyrequired path string Name or slug since query string (date) Default 30 days ago change query "added" | "removed" | "version" limit query integerdefault 25
Responses Code Description Body 200 OK TechChangePage 400 Bad change filter Error 402 Unpaid: counts and the price, never domains Error 404 Not found Error 429 Rate limited. Back off for retry_after seconds. Error 503 Technology data unavailable (cluster down or tables not created yet) Error
curl bash curl -H "Authorization: Bearer ob_live_YOUR_KEY" \
"https://opsblu.com/v1/tech/<technology>/changes?since=2026-10-01&change=&limit=25" GET /v1/sites/{domain}/tech public Current technologies and scan history for one domain (free)
The caller supplied the domain, so nothing is revealed; this is the top of the funnel behind the Infrasight tool. 404 for domains never scanned or under a removal ticket.
Parameters Name In Type Description domainrequired path string Domain or URL
Responses Code Description Body 200 OK SiteTech 400 Not a domain Error 404 Not found Error 429 Rate limited. Back off for retry_after seconds. Error 503 Technology data unavailable (cluster down or tables not created yet) Error
curl bash curl \
"https://opsblu.com/v1/sites/<domain>/tech" Schemas Shapes referenced above. Count is either an integer or the string "<5": small-count suppression protects individual businesses in aggregate views.
Count Counts under 5 are suppressed as "<5".
One of: integer or "<5".
Error Property Type Description error string message string retry_after integer
Coverage Property Type Description businesses_total integer added_today integer cities_covered integer new_this_week integer updated_at string (date-time) cities object[] source "live" Present ("live") when the counters come from the crawl ledger in ScyllaDB; absent on fixture data. states CoverageState[] Live only: per-state crawl ledger. rate_per_hour number Businesses added per hour over the newest window of rate_window_minutes (0 on fixtures, and 0 when the ledger is older than 2 hours = crawl stopped). rate_window_minutes integer stats_computed_at string (date-time) Anchor for projecting rate_per_hour (live only).
CoverageState Per-state crawl counters (aggregates only).
Property Type Description state string state_slug string name string businesses_total Count with_website Count with_phone Count new_today Count cities integer categories integer jobs_done integer jobs_total integer crawl_progress number jobs_done / jobs_total, 0..1 status "complete" | "sweeping" | "planned" computed_at string (date-time) rate_per_hour number rate_window_minutes integer
LiveStats Raw crawl counters attached to Stats when source is "live". top_categories are scraper search terms, not the controlled slug vocabulary.
Property Type Description source "live" scope "national" | "state" | "city" | "city_category" total Count with_website Count with_phone Count with_place_id Count with_coords Count new_today Count cities integer categories integer top_categories object[] jobs_done integer jobs_total integer crawl_progress number states CoverageState[] enriched Count city_category only: value written to depth.enriched (rows whose domain has an opsblu.site_enrichments row; extrapolated when enriched_sampled) enriched_domains integer distinct domains in scope enriched_checked integer domains looked up (capped at 5000) enriched_hits integer of enriched_checked, domains with a site_enrichments row enriched_sampled boolean true when the scope had more than 5000 domains and the ratio was extrapolated enriched_known boolean false when the site_enrichments lookup failed; depth.enriched then keeps the fixture value computed_at string (date-time)
StatsHistory Property Type Description state string state_slug string name string days integer source "live" points object[]
CategoryCount Property Type Description slug string name string count Count
Stats Property Type Description scope string state string city string category string total Count depth Depth categories CategoryCount[] platforms object<Count> tracking object<Count> new_by_month object[] hexes object[] suppressed boolean coverage_complete boolean updated_at string (date-time) source "live" Present ("live") when total, depth.websites, depth.phones and depth.no_website come from the crawl ledger; absent on fixture data. live LiveStats rate_per_hour number national / state scope, live only (0 on fixtures) rate_window_minutes integer stats_computed_at string (date-time)
Signals Property Type Description hot boolean new_in_days integer changed object[] no_website boolean cwv_fail boolean ads_no_tracking boolean
BusinessSummary Property Type Description id string name string category string category_slug string city string state string signals Signals has_phone boolean has_email boolean has_website boolean platform string revealed boolean
CostEstimate Property Type Description records integer hot_records integer already_revealed integer credits integer usd number
CWV Property Type Description lcp number cls number inp number pass boolean
SEO Property Type Description title boolean meta boolean h1 boolean schema boolean sitemap boolean robots boolean
Marketing Property Type Description analytics string[] ads_platforms string[] pixels string[] server_side_tracking boolean consent_tool string
Business Full paid record. No reviews, ratings or photos.
Property Type Description id string name string category string subcategories string[] address string city string state string zip string lat number lng number phone string emails string[] website string domain string socials object<string> first_seen_at string (date-time) last_verified_at string (date-time) status "active" | "closed" | "unknown" web object object with has_website, platform, cwv, seo, ssl_issued_at marketing Marketing signals Signals
Filters Property Type Description state string city string zip string category string q string no_website boolean cwv_fail boolean platform string has_ads boolean has_analytics boolean server_side boolean new_days integer changed_days integer has_phone boolean has_email boolean hot boolean territory_id string
ChangeEvent Property Type Description id string type string at string (date-time) business BusinessSummary
Export Property Type Description export_id string status "pending_confirm" | "ready" | "expired" filters Filters ids string[] estimate CostEstimate estimated_credits integer credits_used integer rows integer format string download_url string created_at string (date-time) confirmed_at string (date-time)
ReportCard Property Type Description id string url string domain string status string cwv_mobile CWV cwv_desktop CWV seo SEO platform string tech_stack string[] marketing Marketing tracking_health object object with score, issues comparison object object with category, zip, peer_count, peer_cwv_pass_rate, peer_ads_rate, peer_server_side_rate
RemovalRequest Property Type Description ticket_id string business_name string domain string requester_email string relationship string status string created_at string (date-time) applies_by string (date-time)
Account Property Type Description id string email string domain string business_email boolean credits_balance integer 1 credit = $0.01 free_credits integer free_credits_expire_at string (date-time) spend_cap number USD per month, 0 = none spent_this_month_usd number connect_bonus_granted boolean created_at string (date-time)
LedgerEntry Property Type Description id string at string (date-time) type "grant" | "topup" | "reveal" | "export" | "expiry" | "adjustment" credits integer balance_after integer note string ref_id string
APIKey Property Type Description id string label string prefix string secret string Only returned on create spend_cap number created_at string (date-time) last_used_at string (date-time) revoked boolean
Territory Property Type Description id string name string kind "city" | "zip" | "polygon" state string city string zip string geojson object alerts object object with email, slack_webhook, webhook, types, cadence
TechPrice What a paid technology list costs.
Property Type Description credits_per_domain integer usd_per_domain number billed_once_per string
TechCount Property Type Description technology string slug string sites Count added_30d Count removed_30d Count computed_at string (date-time)
TechStateCount Property Type Description state string sites Count
TechDetail TechSite Property Type Description domain string first_seen string (date-time) last_seen string (date-time) version string confidence integer 0-100 state string city string revealed boolean Already billed this month before this call
TechSitePage Property Type Description technology string slug string sites Count state string city string items TechSite[] next_cursor string Pass as ?cursor= for the next page truncated boolean Credits ran out mid-page; next_cursor resumes credits_used integer balance_remaining integer price TechPrice
TechChange Property Type Description domain string changed_on string (date) change "added" | "removed" | "version" from_version string to_version string scanned_at string (date-time) revealed boolean
TechChangePage Property Type Description technology string slug string since string (date) change string sites Count added_30d Count removed_30d Count items TechChange[] truncated boolean credits_used integer balance_remaining integer price TechPrice
SiteTech Current technologies and scan history for one domain (free: the caller supplied the domain).
Property Type Description domain string scanned_at string (date-time) source string techs object[] history object[]
TechPaymentRequired