Get started
Quickstart
From a fresh key to a measured answer. Every step below is free except the last one, which spends exactly one check and tells you so first.
In this quickstart you will
- Create a restricted API key
- Authenticate and call whoami
- List businesses and pick a business_id
- Read the visibility report for free
- Quote a one-check prompt before you spend
Step 01
Create a key
Keys are shown once. A new key defaults to every grantable scope and every business. Do not put it in git, logs, or a shared chat.
# Create a key at https://app.scope.online/settings/api-keys export SCOPE_API_KEY=sk_scope_...
Step 02
Call whoami
Confirm the plan, remaining checks, and whether you need a business_id. Multi-business keys require business_id on almost every other call.
curl -H "Authorization: Bearer $SCOPE_API_KEY" \ "https://scope.online/v1/whoami"
Step 03
Pick a business
list_businesses is free. Use the id on every later call. whoami.weekly_brief is the primary business, not necessarily the one the user named.
curl -H "Authorization: Bearer $SCOPE_API_KEY" \ "https://scope.online/v1/list_businesses"
Step 04
Read the report
Reads spend nothing. If engines_measured is less than engines_attempted, say so — do not treat a missing engine as an omit.
curl -H "Authorization: Bearer $SCOPE_API_KEY" \ "https://scope.online/v1/get_visibility_report?business_id=$BUSINESS_ID"
Step 05
Quote before you spend
This is the only step that can spend. confirm defaults to false and returns a quote. Echo the cost. Only send confirm:true after the human agrees.
curl -X POST -H "Authorization: Bearer $SCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"business_id":"YOUR_BUSINESS_ID","prompt":"best plumber near me","confirm":false}' \
"https://scope.online/v1/check_prompt"