Business discovery, with evidence

# Saka developer portal

[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)

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