Business discovery, with evidence

Saka business data API documentation

Business data API reference

The public API uses HTTPS and JSON at https://saka.run/api. The current version is selected by Saka-API-Version: 1. Monetary values are integer microUSD: 1,000,000 microUSD equals one US dollar. Quotes do not charge; a purchase spends prepaid credit only after an explicit cost cap is submitted.

Quote filters and pagination

Specify kind as basic or email and limit from 1 to 200. Optional result_grain is company (default) or location. Filters include country, state, county, city, industry, category, keyword, domain, has_email and has_website. Values are arrays; different filters combine with AND, while values within a filter combine with OR. Use ISO two-letter country codes and a bare hostname for domain. Boolean filters use the strings true or false. The OpenAPI schema lists the accepted industries and categories.

A production quote returns a redacted preview, count, cost_micro, quote_id, expires_at and sometimes next_cursor. Follow that cursor with the same kind and filters. Quotes expire after nine minutes. An empty page is not purchasable. Total counts can be bounded estimates; inspect total_matches_exact, total_matches_is_lower_bound and email_count_is_estimate.

Approve a purchase explicitly

curl https://saka.run/api/data/purchase \
  -H "Authorization: Bearer $SAKA_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"quote_id":"YOUR_QUOTE_ID","max_cost_micro":10000,"idempotency_key":"YOUR_STABLE_PURCHASE_KEY"}'

The example cap is $0.01; replace it only with the amount the user has actually authorized. Save the quote ID, cap and idempotency key before calling purchase. Retry an uncertain request with the identical body and key. A different body under the same key can conflict. Purchases return a receipt, delivered records, cost, balance snapshot, access deadline and source attribution. Same-version access is included for 30 days. Reacquiring a record does not silently extend an existing grant.

Authentication, errors and recovery

Read the Saka OAuth and MCP authentication guide for resource audiences and scopes. Missing or rejected authentication returns 401. Invalid input returns 400; unavailable resources return 404; budget, idempotency or expiry conflicts return 409. A 429 includes Retry-After. Preserve the original purchase request when retrying after a timeout or a transient 503. The live OpenAPI document is the authoritative schema.

When to use Saka

Use Saka to discover businesses by location and industry, preview matching companies, and obtain structured business records with source attribution for research and downstream workflows. Coverage and available fields vary. Published emails are observations, not verified mailboxes or permission to contact someone. Keep the returned source notices with your data.

Self-service onboarding and free previews

Create an account or sign in to preview matching businesses and request free quotes. No payment is required for a quote. Purchases spend prepaid credit and require an explicit maximum cost. Top-ups are $10, $25, or $100; basic records cost $2 per thousand and email-bearing records cost $5 per thousand. Review the exact quote before purchasing.

Authentication and API keys

Saka uses OAuth 2.0 authorization code flow with PKCE through WorkOS Connect. Connect an MCP client to https://saka.run/api/mcp and complete the sign-in flow. Send the resulting access token as Authorization: Bearer TOKEN for REST calls. There is no separate API-key issuing endpoint. The account owner can disable connected-agent access in the account page.

OAuth protected-resource metadata identifies the authorization server. Request the exact resource https://saka.run/api/mcp. Keep tokens private and never embed them in URLs or source code.

REST quickstart

OpenAPI 3.1 specification describes request schemas, filters, responses, authentication and errors. Request a non-charging quote first:

curl https://saka.run/api/data/quote \
  -H "Authorization: Bearer $SAKA_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Saka-API-Version: 1' \
  --data '{"kind":"basic","limit":5,"filters":{"country":["US"],"category":["Plumbing"]}}'

Use POST /api/data/purchase with the returned quote_id, an authorized max_cost_micro, and a stable idempotency_key. Preserve the identical request when retrying a purchase. One US dollar equals 1,000,000 microUSD. Download a purchased receipt with GET /api/data/export?receipt_id=.... Read your balance with GET /api/account.

MCP tools

The purchasing connector at /api/mcp exposes saka_quote, saka_purchase and saka_balance. The read-only purchased-library connector at /api/library/mcp lets agents retrieve existing purchases without making new purchases. Always obtain the user’s spending authorization before buying records.

Sandbox and CLI

Start with the public developer sandbox: no sign-in, credentials or charges, with fictional records and non-purchasable responses. The record template provides a null-valued schema example. Free production quotes exercise authenticated discovery without spending.

Install the official Saka business data CLI from its public release archive for sandbox previews, real quotes, balance and existing exports. This installation does not need private source access. Npm registry publication is pending publisher access. Advanced self-hosted integration testing is described in the operator sandbox recipe, which requires source access and test-provider credentials.

API versioning and deprecation

The current REST contract is version 1. Send Saka-API-Version: 1; omitting it selects version 1 for existing clients. Unsupported versions receive a structured 400 response. Additive fields can appear within a version. Breaking changes require a new version. Before retiring version 1, Saka will publish migration guidance here and provide at least 90 days of notice, with standard Deprecation and Sunset response headers on affected endpoints.

Errors and rate limits

REST errors retain a stable error code, with a human-readable message and a resolution hint. Authenticate after a 401, correct invalid input after a 400, and preserve purchase idempotency on retries. Customer data requests use a token bucket with a burst of 10 and a refill of one request per second per account. Purchased-library requests have a separate bucket. RateLimit-Policy and RateLimit describe the policy and current remaining quota. A 429 includes Retry-After; wait before retrying.