Skip to main content
Docs

Developer quickstart

Load credit, mint a bk_live_ key, run one sourced site check, and read the usage receipt.

Load at least $10 of prepaid credit, mint a key, run one priced site check, and read the receipt. A key is a server-side credential. CORS stays off — do not ship it to a browser.

A free account includes 10 site lookups / month, including headless use. A $10 load is 110 checks in month one, then 100 per $10 after that. Each sourced check is $0.10 USD. Uncovered sites return HTTP 202 with charged: false and are not billed.

1. Load credit and mint a key

  1. Sign in and open Settings → Developer.
  2. Load at least $10 USD.
  3. Create a key. Copy the secret once. Prefixes are bk_live_ in production and bk_test_ locally.
export BUCKY_API_KEY='bk_live_…'

2. Free discovery and an optional priced check

Anonymous coverage is free. The site check is the only priced route.

curl -sS https://buckybuild.com/api/v1/coverage/divisions/ca-on-toronto

Run the next command only when you intend to use a site check. A sourced result can debit prepaid balance even though the HTTP method is GET. Do not run it as a health check or automatic onboarding canary.

curl -sS -i \
  -H "Authorization: Bearer $BUCKY_API_KEY" \
  'https://buckybuild.com/api/v1/sites/check?address=100%20Queen%20St%20W,%20Toronto'

Read usage in the JSON body and the receipt headers: X-Bucky-Receipt-Id, X-Bucky-Price-Usd, X-Bucky-Debit-Usd, X-Bucky-Balance-Usd, X-Bucky-Billing-Reason. Site checks do not support conditional 304 responses, and a cache hit is never a free replay: the 24-hour same-site repeat is the only discount. Inspect the receipt on each result. A 402 reports the shortfall without a second round trip.

curl -sS -H "Authorization: Bearer $BUCKY_API_KEY" \
  https://buckybuild.com/api/v1/usage/balance
curl -sS https://buckybuild.com/openapi.json | head

Coverage, balance and OpenAPI are free. Address suggestions are also free:

SESSION_TOKEN=$(node -p 'crypto.randomUUID()')
curl -sS https://buckybuild.com/api/v1/addresses/suggest \
  -H 'Content-Type: application/json' \
  --data "{\"q\":\"100 Queen St W, Toronto\",\"sessionToken\":\"$SESSION_TOKEN\",\"country\":\"ca\"}"

Pass the chosen suggestion's id as mapboxId to POST /api/v1/addresses/retrieve with the same sessionToken. Retrieve returns { address, lat, lng }; then rotate the token for the next search session. No paid site check is needed for discovery.

3. CLI

The Bucky CLI is in early access and not yet publicly installable. With access, bucky auth login signs you in through your browser, and bucky geo coverage ca-on-toronto calls the same coverage route as above.

Next

  • API — priced check, free reads, redaction, CORS, and the 401 taxonomy.
  • Plans and site lookups — Personal, Professional, and PAYG meters.
  • MCP — agents.
  • CLI — early access: product commands from a terminal or coding agent.

Last updated on