Business discovery, with evidence

# Saka business data API documentation

[Developers](https://saka.run/developers)[API documentation](https://saka.run/docs)[Authentication](https://saka.run/docs/auth)[Sandbox](https://saka.run/sandbox)[CLI](https://saka.run/cli)[About](https://saka.run/about)[Contact](https://saka.run/contact)

## 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.

Saka customer REST endpointsMethod and endpointPurpose`GET /api/account`Read your balance and connected-agent access setting.`POST /api/data/quote`Preview matches and obtain an account-specific quote.`POST /api/data/purchase`Approve the quoted purchase with a maximum authorized charge.`GET /api/data/export?receipt_id=…`Export an owned purchase as CSV, including source attribution.`POST /api/sandbox/quote`Try a fictional-data quote without authentication or charges.

## 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

```sh
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](https://saka.run/docs/auth) 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](https://saka.run/api/openapi.json) 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](https://saka.run/app) 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](https://saka.run/.well-known/oauth-protected-resource/api/mcp) 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](https://saka.run/api/openapi.json) describes request schemas, filters, responses, authentication and errors. Request a non-charging quote first:

```sh
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](https://saka.run/sandbox): no sign-in, credentials or charges, with fictional records and non-purchasable responses. The [record template](https://saka.run/record-template.json) provides a null-valued schema example. Free production quotes exercise authenticated discovery without spending.

[Install the official Saka business data CLI](https://saka.run/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](https://github.com/sirerun/saka/blob/main/deploy/commerce/sandbox.md), 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.