Business discovery, with evidence

Saka developer portal

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.