{"components":{"schemas":{"Account":{"properties":{"account_id":{"type":"string"},"agent_access_enabled":{"type":"boolean"},"balance_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"csrf_token":{"description":"Browser mutation token; empty for bearer authentication.","type":"string"},"email":{"type":"string"}},"required":["account_id","email","balance_micro","csrf_token","agent_access_enabled"],"type":"object"},"BusinessRecord":{"description":"Public commercial projection of a versioned business record. Email fields are null for basic purchases. Email purchases include published_unverified status and public source evidence; no named decision-makers or verified mailbox guarantee. Other envelope fields can be present, including null fields reserved for excluded data.","properties":{"business_name":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"county":{"type":["string","null"]},"email":{"type":["string","null"]},"email_evidence":{"type":["string","null"]},"email_source_url":{"type":["string","null"]},"email_status":{"type":["string","null"]},"industry":{"type":["string","null"]},"location_count":{"description":"Number of matching source rows encountered for this physical location; bounded scan may omit further duplicates.","minimum":1,"type":"integer"},"location_count_is_estimate":{"description":"True because the bounded preview scan may not encounter every duplicate source row.","type":"boolean"},"phone":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"quality_flags":{"description":"Review hints for possible personal-email/name mismatches and scheduling or social URLs; these do not verify ownership or reachability.","items":{"type":"string"},"type":["array","null"]},"record_id":{"type":"string"},"region":{"type":["string","null"]},"research_date":{"type":["string","null"]},"revision":{"minimum":0,"type":"integer"},"schema_version":{"type":"string"},"segment":{"type":["string","null"]},"source_url":{"type":["string","null"]},"state":{"type":["string","null"]},"street_address":{"type":["string","null"]},"website":{"type":["string","null"]},"website_last_checked":{"format":"date-time","type":["string","null"]},"website_status":{"description":"Unknown unless a website check has been performed.","type":["string","null"]}},"required":["record_id","revision"],"type":"object"},"Error":{"properties":{"error":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}},"required":["error"],"type":"object"},"Preview":{"properties":{"business_name":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"industry":{"type":["string","null"]},"location_count":{"description":"Number of matching source rows encountered for this physical location; bounded scan may omit further duplicates.","minimum":1,"type":"integer"},"location_count_is_estimate":{"description":"True because the bounded preview scan may not encounter every duplicate source row.","type":"boolean"},"segment":{"type":["string","null"]},"state":{"type":["string","null"]}},"type":"object"},"PurchaseRequest":{"additionalProperties":false,"properties":{"idempotency_key":{"description":"Stable unique key for this logical purchase; reuse the same quote and cap on retries.","maxLength":128,"minLength":1,"type":"string"},"max_cost_micro":{"description":"Maximum authorized debit in microUSD. Required even when the quoted cost is zero.","format":"int64","minimum":0,"type":"integer"},"quote_id":{"minLength":1,"type":"string"}},"required":["quote_id","max_cost_micro","idempotency_key"],"type":"object"},"PurchaseResponse":{"properties":{"access_until":{"description":"End of the purchased record-version access window. Free reacquisition does not extend existing access.","format":"date-time","type":"string"},"balance_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"cost_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"next_cursor":{"type":"string"},"receipt_id":{"type":"string"},"records":{"items":{"$ref":"#/components/schemas/BusinessRecord"},"type":"array"},"source_attribution":{"additionalProperties":{"items":{"$ref":"#/components/schemas/SourceAttribution"},"type":"array"},"description":"Source notices and licensing metadata indexed by record_id. Preserve with redistributed data.","type":"object"}},"required":["receipt_id","cost_micro","balance_micro","records","access_until","source_attribution"],"type":"object"},"QuoteRequest":{"additionalProperties":false,"properties":{"cursor":{"maxLength":4096,"type":"string"},"filters":{"additionalProperties":false,"description":"Supported filters: country, state, county, city, industry, category, keyword, domain, has_email, and has_website. Filters combine with AND; values within each array combine with OR. Country uses supported ISO country codes. Domain is a bare hostname. Keyword accepts one phrase. email kind implies has_email=true.","properties":{"category":{"items":{"enum":["Auto Repair","Bakery","Cafe","Chiropractor","Cleaning","Coffee Shop","Construction","Dentist","Electrical","Grocery Store","HVAC","Hotel","Landscaping","Law Firm","Motel","Pharmacy","Plumbing","Professional Services","Restaurant","Roofing","Supermarket"],"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"city":{"items":{"maxLength":256,"minLength":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"country":{"items":{"maxLength":256,"minLength":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"county":{"items":{"maxLength":256,"minLength":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"domain":{"items":{"maxLength":256,"minLength":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"has_email":{"items":{"enum":["true","false"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"},"has_website":{"items":{"enum":["true","false"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"},"industry":{"items":{"enum":["Automotive","Construction","Food and Beverage","Health Care","Home Services","Hospitality","Professional Services","Retail"],"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"keyword":{"items":{"description":"One free-text phrase matched against business names and mapped categories.","maxLength":256,"minLength":1,"type":"string"},"maxItems":1,"minItems":1,"type":"array"},"state":{"items":{"maxLength":256,"minLength":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"type":"object"},"kind":{"description":"basic or email; email requires public published-email evidence.","enum":["basic","email"],"type":"string"},"limit":{"description":"Maximum unique rows returned in this preview page.","maximum":200,"minimum":1,"type":"integer"},"result_grain":{"description":"company deduplicates matching locations by normalized name and address, phone, or website; location preserves branches; both modes eliminate duplicate source rows for the same physical location.","enum":["company","location"],"type":"string"}},"required":["limit","kind"],"type":"object"},"QuoteResponse":{"properties":{"balance_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"cost_all_basic_micro":{"description":"Undiscounted list price for total_matches at the published basic rate; a lower bound when total_matches_is_lower_bound=true.","format":"int64","type":"integer"},"cost_all_email_micro":{"description":"Undiscounted list-price estimate for email matches, whose error direction is unknown when counting is incomplete.","format":"int64","type":"integer"},"cost_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"count":{"description":"Unique company or location rows returned on this page; separate from total_matches.","minimum":0,"type":"integer"},"email_count_is_estimate":{"type":"boolean"},"expires_at":{"format":"date-time","type":"string"},"next_cursor":{"type":"string"},"preview":{"items":{"$ref":"#/components/schemas/Preview"},"type":"array"},"quote_id":{"type":"string"},"total_matches":{"description":"Filtered unique physical locations. Exact only when total_matches_exact=true; otherwise a lower bound from a bounded count or preview scan.","minimum":0,"type":"integer"},"total_matches_exact":{"type":"boolean"},"total_matches_is_lower_bound":{"description":"When true, total_matches and cost_all_basic_micro are lower bounds, not complete inventory quotes; email totals/prices remain estimates of unknown direction.","type":"boolean"},"total_with_eligible_email":{"description":"Estimate from matching redistributable email observations. Attribution checks and bounded sampling can change the fully eligible total in either direction.","minimum":0,"type":"integer"}},"required":["quote_id","expires_at","cost_micro","balance_micro","count","total_matches","total_with_eligible_email","total_matches_exact","total_matches_is_lower_bound","email_count_is_estimate","cost_all_basic_micro","cost_all_email_micro","preview"],"type":"object"},"SourceAttribution":{"properties":{"dataset_name":{"description":"Buyer-readable source dataset name.","type":"string"},"license_basis":{"type":"string"},"release":{"type":"string"},"retrieved_at":{"format":"date-time","type":"string"},"source":{"type":"string"},"source_asset":{"description":"Upstream release asset identifier; use source_documentation for a readable dataset explanation.","type":"string"},"source_documentation":{"items":{"type":"string"},"type":"array"},"source_licenses":{"items":{"type":"string"},"type":"array"},"source_notices":{"items":{"type":"string"},"type":["array","null"]},"source_provider":{"type":["string","null"]},"source_record_id":{"type":"string"}},"type":"object"}},"securitySchemes":{"WorkOSBearer":{"bearerFormat":"WorkOS Connect JWT","description":"User access token for the exact resource https://saka.run/api/mcp. Agent access is enabled by default and can be disabled by the owner in Saka. Purchases still require a funded balance and an explicit cost cap. No Saka API-key issuing endpoint exists.","scheme":"bearer","type":"http"},"WorkOSOAuth":{"description":"WorkOS Connect authorization code flow with PKCE. Register the connector redirect URI in WorkOS or use supported dynamic registration. Request resource=https://saka.run/api/mcp. Use discovery at https://inspired-countryside-98.authkit.app/.well-known/oauth-authorization-server.","flows":{"authorizationCode":{"authorizationUrl":"https://inspired-countryside-98.authkit.app/oauth2/authorize","scopes":{"openid":"Identify the WorkOS user; agent access is enabled by default and can be disabled in Saka."},"tokenUrl":"https://inspired-countryside-98.authkit.app/oauth2/token"}},"type":"oauth2"}}},"info":{"description":"Find permitted business records, obtain a free quote, and make an explicit capped purchase from a human-funded balance. Basic records cost 2000 microUSD; published-email records cost 5000 microUSD inclusive. Published emails are unverified. Same-account record-version access lasts 30 days; quotes account for existing access. OAuth identity is tied to an individual prepaid balance. Agent spending is enabled by default and can be disabled in /app; purchases still require sufficient prepaid funds and an explicit maximum cost. Always preserve the user's budget and the purchase idempotency key. This specification describes implemented interfaces; production availability requires activation.","title":"Saka prepaid business data","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/account":{"get":{"description":"Accepts a WorkOS Connect bearer token when agent access is enabled (on by default; the owner can disable it). Also available to the browser's secure session. Does not charge.","operationId":"getSakaAccount","parameters":[{"description":"REST API version. Version 1 remains the default. Breaking changes require a new version; retirement receives at least 90 days notice in /docs with Deprecation and Sunset headers.","in":"header","name":"Saka-API-Version","required":false,"schema":{"default":"1","enum":["1"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Authenticated WorkOS user account and balance."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"authentication_required."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"billing_unavailable."}},"summary":"Read your prepaid balance and agent access setting"}},"/api/data/export":{"get":{"operationId":"exportSakaPurchase","parameters":[{"in":"query","name":"receipt_id","required":true,"schema":{"minLength":1,"type":"string"}},{"description":"REST API version. Version 1 remains the default. Breaking changes require a new version; retirement receives at least 90 days notice in /docs with Deprecation and Sunset headers.","in":"header","name":"Saka-API-Version","required":false,"schema":{"default":"1","enum":["1"],"type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"CSV of the purchased record version, rechecked for current public eligibility. No extra charge. Available until access_until, subject to suppression. CSV includes a source_attribution JSON column; retain it when redistributing records."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request: invalid_request."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing, invalid, expired, or revoked authentication, or owner has not enabled agent spending: authentication_required."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment dispute holds this account: payment_under_review."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Quote, receipt, or permitted data unavailable to this account: data_unavailable."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"spend_limit_exceeded, idempotency_conflict, or quote_or_access_expired. Do not silently raise a spending cap."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"rate_limited; wait according to Retry-After before retrying.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporary provider or persistence failure: service_unavailable. Retry the same purchase key and body."}},"summary":"Download a purchased result as CSV"}},"/api/data/purchase":{"post":{"description":"Spends prepaid balance. max_cost_micro is mandatory and must be within the user's authorized budget. Set a unique idempotency_key for each logical purchase; persist and reuse the identical request after timeouts. Reusing a key with a different quote returns idempotency_conflict. A replay returns the original completed charge; preserve the original cap and request body. An idempotent replay returns the original receipt and original balance snapshot. Current eligibility and the 30-day access window still apply.","operationId":"purchaseSakaBusinesses","parameters":[{"description":"REST API version. Version 1 remains the default. Breaking changes require a new version; retirement receives at least 90 days notice in /docs with Deprecation and Sunset headers.","in":"header","name":"Saka-API-Version","required":false,"schema":{"default":"1","enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}},"description":"Successful request. All monetary values are integer microUSD; 1000000 microUSD = 1 USD."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request: invalid_request."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing, invalid, expired, or revoked authentication, or owner has not enabled agent spending: authentication_required."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"insufficient_balance. Ask the human owner to top up in Saka; agents cannot create a payment."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment dispute holds this account: payment_under_review."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Quote, receipt, or permitted data unavailable to this account: data_unavailable."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"spend_limit_exceeded, idempotency_conflict, or quote_or_access_expired. Do not silently raise a spending cap."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"rate_limited; wait according to Retry-After before retrying.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporary provider or persistence failure: service_unavailable. Retry the same purchase key and body."}},"summary":"Purchase a quote with an explicit spending cap","x-openai-isConsequential":true}},"/api/data/quote":{"post":{"description":"No charge. Select basic or email records, with 1–200 matches per page. An email quote requires redistributable public evidence. Returns a redacted preview, exact current price, opaque pagination cursor, and a quote valid for nine minutes. Empty pages have count=0 and empty quote_id; do not purchase an empty quote. Follow next_cursor with the same filters and kind.","operationId":"quoteSakaBusinesses","parameters":[{"description":"REST API version. Version 1 remains the default. Breaking changes require a new version; retirement receives at least 90 days notice in /docs with Deprecation and Sunset headers.","in":"header","name":"Saka-API-Version","required":false,"schema":{"default":"1","enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}},"description":"Successful request. All monetary values are integer microUSD; 1000000 microUSD = 1 USD."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request: invalid_request."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing, invalid, expired, or revoked authentication, or owner has not enabled agent spending: authentication_required."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment dispute holds this account: payment_under_review."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Quote, receipt, or permitted data unavailable to this account: data_unavailable."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"spend_limit_exceeded, idempotency_conflict, or quote_or_access_expired. Do not silently raise a spending cap."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"rate_limited; wait according to Retry-After before retrying.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporary provider or persistence failure: service_unavailable. Retry the same purchase key and body."}},"summary":"Preview matching businesses and their purchase price"}},"/api/sandbox/quote":{"post":{"description":"No production data, ledger access, purchases, account creation or charges. Validates QuoteRequest and applies filters to two fictional plumbing businesses in California. Cursor must be empty. Simulated prices use current public unit prices. Never returns a purchasable quote_id.","operationId":"previewSakaSandbox","parameters":[{"description":"REST API version. Version 1 remains the default. Breaking changes require a new version; retirement receives at least 90 days notice in /docs with Deprecation and Sunset headers.","in":"header","name":"Saka-API-Version","required":false,"schema":{"default":"1","enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"can_purchase":{"const":false},"charged_micro":{"const":0},"count":{"type":"integer"},"preview":{"items":{"$ref":"#/components/schemas/Preview"},"type":"array"},"sandbox":{"const":true},"simulated_cost_micro":{"description":"Integer microUSD. 1000000 equals one US dollar. Refunds can leave a negative balance.","format":"int64","type":"integer"},"total_matches":{"type":"integer"}},"required":["sandbox","can_purchase","charged_micro","simulated_cost_micro","count","total_matches","preview"],"type":"object"}}},"description":"Fictional preview. sandbox=true, can_purchase=false and charged_micro=0."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid sandbox request."}},"security":[],"summary":"Try a free fictional-data quote without credentials"}}},"security":[{"WorkOSOAuth":["openid"]},{"WorkOSBearer":[]}],"servers":[{"url":"https://saka.run"}],"x-saka-mcp":{"protected_resource_metadata":"https://saka.run/.well-known/oauth-protected-resource/api/mcp","tools":["saka_quote","saka_purchase","saka_balance"],"transport":"streamable-http","url":"https://saka.run/api/mcp"}}