Skip to content

The ScanFree REST API

Everything your agent can do over MCP, over plain HTTP: the same actions, run by the same code, with the same keys, scopes and limits. Free for members.

The base address
https://app.scanfree.dev/api/v1

Every endpoint is described in an OpenAPI 3.1 document, generated from the same schemas as the MCP tools: /api/v1/openapi.json (public, no key needed).

Keys and sign-in

Send a key in the Authorization header on every call. Make one on your MCP page; the keys that work for MCP work here, and so do OAuth access tokens (sfo_…) an app got from the sign-in on the consent screen. Your account must be verified. A revoked key, or a blocked account, stops working on the next call.

Every call
Authorization: Bearer sf_live_YOUR_KEY
ScopeWhat it allowsWho has it
scan:readRead scans, orders, sites and the account.Every key and sign-in
scan:writeStart scans, set up orders, change phrases, sites, pages, claims, programs and share links.Every key and sign-in
order:writeStop an order and ask for a refund. Each asks the person to confirm first.Off unless ticked ("Stop orders and ask for refunds") when making the key or on the consent screen
account:writeChange the email choices and make the data export.Off unless ticked ("Change email choices and make a data export") when making the key or on the consent screen

Each endpoint below names its scope. Calling one without it answers 403 with missing_scope and grant_url, the page where the person grants it.

Requests and answers

  • Ids go in the path (/orders/{order_id}), under the same names the MCP tools use. GET and DELETE take their other parameters in the query; POST, PUT and PATCH take a JSON object (Content-Type: application/json).
  • A parameter an endpoint doesn’t take is refused with 400 invalid_input, never ignored.
  • A 200 answer is the tool’s own answer: it always has status (ok, or a state such as running, queued or complete) and often message in plain words.
  • Nothing returns AI answer text in bulk: one short quote at most, as on MCP and in the downloads. No endpoint runs ScanFree’s own AI except /question-suggestions, which is optional and free; /site-facts is the no-AI way.

Errors

Every error has the same shape. code is stable: it is the same word the MCP tool answers in status. Some errors add details, such as missing_scope, grant_url or problems.

An error
{
  "error": {
    "code": "not_found",
    "message": "No such order on this account."
  }
}
HTTPcodeWhat it means
400invalid_input, invalid_questionsA parameter is missing, has the wrong type or value, or isn't one this endpoint takes.
401missing_token, invalid_tokenNo key, or one that was revoked, has expired, or belongs to an unverified or blocked account.
403forbidden, verify_email, revokedThe key lacks the endpoint's scope (see missing_scope), or the agent was revoked.
404not_foundNo such order, site, scan, phrase or page on this account. Another account's is not found too, never forbidden.
409invalid_confirmation, not_available, refused, already_running, needs_review, pausedValid, but not possible now: a feature that is switched off (not_available), an order in the wrong state, a refused stop or refund, or a bad confirm_token.
429rate_limited, too_many_failures, limited, limit_reached, daily_limitToo many requests (wait Retry-After seconds), or a product limit such as free scans this month, suggestions today or one export an hour.
500internal_errorOur fault. Try again.

Switched-off features answer 409 not_available, the same as their MCP tools.

Two-step confirmation

Endpoints marked ⚠ stop, retire, remove or ask for money back. They never act on the first call:

  1. The first call checks everything, changes nothing and answers 409 with a plain summary and a confirm_token.
  2. Show the summary to the person. Only if they agree, send exactly the same request again with the header ScanFree-Confirm: <confirm_token> (or confirm_token in the JSON body).

A token works once, for 10 minutes, for the same account, endpoint and parameters. Anything else answers 409 invalid_confirmation and nothing changes. Tokens are shared with MCP: one given to an MCP call works on the matching REST call.

The first answer
{
  "status": "needs_confirmation",
  "tool": "manage_order",
  "action": "stop",
  "summary": "Stop order 00000000 (example.com): 2 checks left are not run; the refund the policy gives today is shown here.",
  "confirm_token": "sfc_…",
  "expires_at": "2026-11-21T10:10:00.000Z",
  "message": "Show this summary to the person…"
}

Pagination

None. Lists are short and capped where they could grow: /scans takes limit (up to 50), the keyword lists take limit (up to 1,000). Downloads of a whole order come from /orders/{order_id}/report.

Limits

  • 60 requests a minute per key or app, and 60 a minute per account across all of them. MCP and REST share both.
  • Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Policy for the tighter of the two. Past the limit: 429 rate_limited with Retry-After in seconds.
  • More than 20 failed sign-ins a minute from one address: 429 too_many_failures.
  • The product limits are the website’s: 3 free scans a month (shared with the website), 5 suggestion or site-facts runs a day, 10 reach runs a day, robots checks 30 an hour. GET /scans/{scan_id} waits at most 25 seconds.

Versioning

v1 is frozen once public: additions only (new endpoints, new optional parameters, new fields in answers). A breaking change means v2, at a new address. Read answers leniently: ignore fields you don’t know.

What stays off the API

Signing in and making keys, deleting the account, and paying. An agent can price an order and get a Checkout link, but a person pays.

Endpoints

Examples use placeholder ids and illustrative values. Replace sf_live_YOUR_KEY with your key.

Scans

POST /scans

Start a free scan (or, without questions, get suggestions first).

Scope
scan:write
MCP tool
start_scan
Body fieldTypeRequiredValues and limits
urlstringYesThe business website, for example example.com
site_typestringYeslocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
citystringNoCity and state for local types, e.g. Boise, Idaho
questionsarray of stringNo1 to 10 items

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the start_scan page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/scans" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com","site_type":"local_service","city":"Boise, Idaho","questions":["Which plumber in Boise fixes leaks on weekends?"]}'

GET /scans

Recent scans.

Scope
scan:read
MCP tool
list_scans
ParameterInTypeRequiredValues and limits
limitqueryintegerNo1 to 50

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the list_scans page.

Example
curl "https://app.scanfree.dev/api/v1/scans?limit=1" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /scans/{scan_id}

A scan's progress, then its report.

Scope
scan:read
MCP tool
get_scan
ParameterInTypeRequiredValues and limits
scan_idpathstringYes
wait_secondsqueryintegerNo0 to 25

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_scan page.

Example
curl "https://app.scanfree.dev/api/v1/scans/00000000-0000-4000-8000-000000000001?wait_seconds=0" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /scans/{scan_id}/explanation

A finished scan in plain words.

Scope
scan:read
ParameterInTypeRequiredValues and limits
scan_idpathstringYesA finished scan of this account

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the explain_result page.

Example
curl "https://app.scanfree.dev/api/v1/scans/00000000-0000-4000-8000-000000000001/explanation" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /scans/{scan_id}/share

Whether the scan's public share link is on.

Scope
scan:read
MCP tool
share_link action get
ParameterInTypeRequiredValues and limits
scan_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl "https://app.scanfree.dev/api/v1/scans/00000000-0000-4000-8000-000000000001/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /scans/{scan_id}/share

Switch the scan's public share link on.

Scope
scan:write
MCP tool
share_link action on
ParameterInTypeRequiredValues and limits
scan_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/scans/00000000-0000-4000-8000-000000000001/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

DELETE /scans/{scan_id}/share

Switch the scan's public share link off.

Scope
scan:write
MCP tool
share_link action off
ParameterInTypeRequiredValues and limits
scan_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl -X DELETE "https://app.scanfree.dev/api/v1/scans/00000000-0000-4000-8000-000000000001/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /site-facts

A site's facts, read from up to 4 pages, for your AI to write questions (no AI).

Scope
scan:read
ParameterInTypeRequiredValues and limits
urlquerystringYes
site_typequerystringYeslocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
cityquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the suggest_questions page.

Example
curl "https://app.scanfree.dev/api/v1/site-facts?url=example.com&site_type=local_service" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /question-suggestions

Twelve question suggestions from ScanFree's own model (optional, free).

Scope
scan:read
ParameterInTypeRequiredValues and limits
urlquerystringYes
site_typequerystringYeslocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
cityquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the suggest_questions page.

Example
curl "https://app.scanfree.dev/api/v1/question-suggestions?url=example.com&site_type=local_service" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

Orders

GET /orders

Every paid order at a glance.

Scope
scan:read

No parameters.

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_dashboard page.

Example
curl "https://app.scanfree.dev/api/v1/orders" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders

Price an order and get a Checkout link for a person to pay.

Scope
scan:write
MCP tool
create_order
Body fieldTypeRequiredValues and limits
presetstringNocheapest, recommended, premium. A ready-made order from the settings; other arguments given override its parts
phrasesintegerNo1 to 200
frequencystringNoone_time, monthly, biweekly, weekly
monthsintegerNo1 to 12
paystringNoonce, monthly
routesarray of stringNoat most 30 items
researchintegerNo0 to 100

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the create_order page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"recommended"}'

GET /orders/{order_id}

One paid order in full.

Scope
scan:read
MCP tool
get_order
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_order page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/status

The check running now, the last one and the next.

Scope
scan:read
MCP tool
check_status
ParameterInTypeRequiredValues and limits
order_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the check_status page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/status" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/matrix

One check's phrases × AIs.

Scope
scan:read
MCP tool
get_matrix
ParameterInTypeRequiredValues and limits
order_idpathstringYes
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_matrix page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/matrix?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/pages-to-beat

The pages AI cited, per phrase.

Scope
scan:read
ParameterInTypeRequiredValues and limits
order_idpathstringYes
phrase_idquerystringNo
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_pages_to_beat page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/pages-to-beat?phrase_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/actions

One check's actions, with their hand-off text.

Scope
scan:read
MCP tool
list_actions
ParameterInTypeRequiredValues and limits
order_idpathstringYes
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the list_actions page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/actions?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/summary

The one thing, and what moved.

Scope
scan:read
ParameterInTypeRequiredValues and limits
order_idpathstringYes
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_check_summary page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/summary?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/gap

Did the work close the gap.

Scope
scan:read
MCP tool
get_gap
ParameterInTypeRequiredValues and limits
order_idpathstringYes
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_gap page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/gap?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/report

A 10-minute download link: CSV, JSON or PDF.

Scope
scan:read
MCP tool
get_report
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
formatquerystringYescsv, json, pdf
check_idquerystringNoOne check (from get_matrix or get_order)

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_report page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/report?format=csv" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /checks/{check_id}/explanation

A finished check of a paid order in plain words.

Scope
scan:read
ParameterInTypeRequiredValues and limits
check_idpathstringYesA finished check of a paid order (from get_matrix or check_status)

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the explain_result page.

Example
curl "https://app.scanfree.dev/api/v1/checks/00000000-0000-4000-8000-000000000003/explanation" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /orders/{order_id}/setup

Set the website and phrases of a paid order.

Scope
scan:write
MCP tool
order_setup
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard (orders_waiting_for_setup)
Body fieldTypeRequiredValues and limits
site_idstringNo
urlstringNo
site_typestringNolocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
citystringNo
namestringNoThe business name
phrasesarray of stringYes1 to 200 items

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the order_setup page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/setup" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com","site_type":"local_service","city":"Boise, Idaho","phrases":["Which plumber in Boise fixes leaks on weekends?"]}'

POST /orders/{order_id}/notes

Add a note to the order's chart.

Scope
scan:write
MCP tool
manage_order action add_note
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
textstringYes0 to 200 characters. For add_note: 3 to 200 characters

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the manage_order page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/notes" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Which plumber in Boise fixes leaks on weekends?"}'

Stripe's page to replace the card and see invoices.

Scope
scan:read
MCP tool
manage_order action billing_link
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the manage_order page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/billing-link" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/stop ⚠

Stop the order: no more checks or payments. Asks for confirmation first (see Two-step confirmation).

Scope
order:write
MCP tool
manage_order action stop
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard

Answers: 200 the tool’s answer; 409 needs_confirmation, then the same request with ScanFree-Confirm; errors as above. The answer’s fields are on the manage_order page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/stop" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/refund-request ⚠

Ask for the refund the policy gives. Asks for confirmation first (see Two-step confirmation).

Scope
order:write
MCP tool
manage_order action request_refund
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
notestringNo0 to 1000 characters. For request_refund: why, for the person at ScanFree
stopbooleanNoFor request_refund: also ask to stop the order

Answers: 200 the tool’s answer; 409 needs_confirmation, then the same request with ScanFree-Confirm; errors as above. The answer’s fields are on the manage_order page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/refund-request" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"We stopped the service."}'

GET /orders/{order_id}/addons/quote

The price of adding to the order (nothing is charged).

Scope
scan:read
MCP tool
addons action quote
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
kindquerystringYesphrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add
countqueryintegerNo1 to 200. For phrases and checks
route_keyquerystringNo0 to 120 characters. For engine: an AI key (create_order's routes)
competitorsqueryintegerNo0 to 100. For research (competitors a month) and backlinks (competitors besides your site)
cadencequerystringNomonthly, every_check. For backlinks
sizequeryintegerNo-9007199254740991 to 9007199254740991. For keywords: 100 or 500
monthsqueryintegerNo2 to 24. For upgrade: months in all

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the addons page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/addons/quote?kind=phrases&count=1" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/addons ⚠

Add to the order: a Checkout link for the person to pay (a monthly-billed order's next payments: confirm first). Asks for confirmation first (see Two-step confirmation).

Scope
scan:write
MCP tool
addons action apply
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
kindstringYesphrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add
countintegerNo1 to 200. For phrases and checks
route_keystringNo0 to 120 characters. For engine: an AI key (create_order's routes)
route_keysarray of stringNoat most 20 items. For recheck: AIs of this order (default all)
competitorsintegerNo0 to 100. For research (competitors a month) and backlinks (competitors besides your site)
cadencestringNomonthly, every_check. For backlinks
sizeintegerNo-9007199254740991 to 9007199254740991. For keywords: 100 or 500
keywordsarray of stringNoat most 600 items. For keywords: your own list (optional)
monthsintegerNo2 to 24. For upgrade: months in all

Answers: 200 the tool’s answer; 409 needs_confirmation, then the same request with ScanFree-Confirm; errors as above. The answer’s fields are on the addons page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/addons" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"phrases","count":1}'

The competitors the backlinks add-on checks.

Scope
scan:write
MCP tool
addons action set_backlink_competitors
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
domainsarray of stringYesat most 20 items. For set_backlink_competitors

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the addons page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/backlink-competitors" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":[]}'

GET /orders/{order_id}/share

Whether the order report's public share link is on.

Scope
scan:read
MCP tool
share_link action get
ParameterInTypeRequiredValues and limits
order_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /orders/{order_id}/share

Switch the order report's public share link on.

Scope
scan:write
MCP tool
share_link action on
ParameterInTypeRequiredValues and limits
order_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

DELETE /orders/{order_id}/share

Switch the order report's public share link off.

Scope
scan:write
MCP tool
share_link action off
ParameterInTypeRequiredValues and limits
order_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.

Example
curl -X DELETE "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/share" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

Phrases

GET /orders/{order_id}/phrases

The order's phrases.

Scope
scan:read
MCP tool
phrases action list
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/phrases" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/phrases

Add a phrase in a free slot.

Scope
scan:write
MCP tool
phrases action add
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
textstringYes0 to 300 characters. For add and replace: the new phrase

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/phrases" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Which plumber in Boise fixes leaks on weekends?"}'

PUT /orders/{order_id}/phrases/{phrase_id}

Retire a phrase and add another in its slot.

Scope
scan:write
MCP tool
phrases action replace
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
phrase_idpathstringYesFor history, replace, retire, set_keywords: a phrase id from action list
Body fieldTypeRequiredValues and limits
textstringYes0 to 300 characters. For add and replace: the new phrase

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/phrases/00000000-0000-4000-8000-000000000005" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Which plumber in Boise fixes leaks on weekends?"}'

DELETE /orders/{order_id}/phrases/{phrase_id} ⚠

Retire a phrase (its history is kept). Asks for confirmation first (see Two-step confirmation).

Scope
scan:write
MCP tool
phrases action retire
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
phrase_idpathstringYesFor history, replace, retire, set_keywords: a phrase id from action list

Answers: 200 the tool’s answer; 409 needs_confirmation, then the same request with ScanFree-Confirm; errors as above. The answer’s fields are on the phrases page.

Example
curl -X DELETE "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/phrases/00000000-0000-4000-8000-000000000005" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/phrases/{phrase_id}/history

One phrase per check and AI.

Scope
scan:read
MCP tool
phrases action history
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
phrase_idpathstringYesFor history, replace, retire, set_keywords: a phrase id from action list

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/phrases/00000000-0000-4000-8000-000000000005/history" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /orders/{order_id}/keywords

The keyword package's Google data.

Scope
scan:read
MCP tool
phrases action keywords
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
limitqueryintegerNo1 to 1000. For keywords: cap on each list (default 100)

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/keywords?limit=1" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /orders/{order_id}/keywords

Set related Google keywords (for one phrase, or the package's list).

Scope
scan:write
MCP tool
phrases action set_keywords
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
keywordsarray of stringYesat most 1000 items. For set_keywords
phrase_idstringNoFor history, replace, retire, set_keywords: a phrase id from action list

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/keywords" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["emergency plumber boise"]}'

Claims

GET /orders/{order_id}/claims

What AI said about the business in a check.

Scope
scan:read
MCP tool
claims action list
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/claims?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/claims/wrong

Mark a claim wrong (or take the mark off).

Scope
scan:write
MCP tool
claims action mark_wrong
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
claimstringYes0 to 300 characters
polaritystringYespositive, negative, neutral
undobooleanNoFor mark_wrong: take the mark off
check_idstringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/claims/wrong" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim":"Open on Sundays","polarity":"negative"}'

PUT /orders/{order_id}/claims/fixed-on

The day a correction went live.

Scope
scan:write
MCP tool
claims action fixed_on
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
Body fieldTypeRequiredValues and limits
claimstringYes0 to 300 characters
polaritystringYespositive, negative, neutral
fixed_onstringYesFor fixed_on: YYYY-MM-DD, or empty
check_idstringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/claims/fixed-on" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim":"Open on Sundays","polarity":"negative","fixed_on":"2026-11-20"}'

GET /orders/{order_id}/facts-check

The facts check: what AI said that doesn't match your facts.

Scope
scan:read
MCP tool
claims action facts
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
check_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/facts-check?check_id=%E2%80%A6" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /orders/{order_id}/facts-check/{flag_id}

Mark a facts check flag wrong or right (or clear the mark).

Scope
scan:write
MCP tool
claims action mark_fact
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
flag_idpathstringYesFor mark_fact: a flag_id from action facts
Body fieldTypeRequiredValues and limits
markstringYeswrong, right, clear. For mark_fact

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/facts-check/00000000-0000-4000-8000-000000000009" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mark":"wrong"}'

Programs

GET /orders/{order_id}/programs

The directory, press and blog checklists.

Scope
scan:read
MCP tool
programs action get
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the programs page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/programs" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /orders/{order_id}/programs/{program}/items/{item}

The person's status for one place.

Scope
scan:write
MCP tool
programs action set_item
ParameterInTypeRequiredValues and limits
order_idpathstringYesAn order id from get_dashboard
programpathstringYes
itempathstringYesAn item key from action get
Body fieldTypeRequiredValues and limits
statusstringYestodo, submitted, live
urlstringNo0 to 500 characters. For status live: the page's address

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the programs page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/programs/directory/items/yelp" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"submitted"}'

Published pages

GET /orders/{order_id}/published-pages

Pages published for the order's site.

Scope
scan:read
MCP tool
published_pages action list
ParameterInTypeRequiredValues and limits
order_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/published-pages" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /orders/{order_id}/published-pages

Track a page published for the order's site.

Scope
scan:write
MCP tool
published_pages action add
ParameterInTypeRequiredValues and limits
order_idpathstringYes
Body fieldTypeRequiredValues and limits
urlstringYes0 to 500 characters. For add and set_content_page
kindstringNopress, blog, listing, other, mention
live_onstringNoYYYY-MM-DD; for add (default today) and update

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/orders/00000000-0000-4000-8000-000000000002/published-pages" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

GET /sites/{site_id}/published-pages

Pages published for a site.

Scope
scan:read
MCP tool
published_pages action list
ParameterInTypeRequiredValues and limits
site_idpathstringYes

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/published-pages" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /sites/{site_id}/published-pages

Track a page published for a site.

Scope
scan:write
MCP tool
published_pages action add
ParameterInTypeRequiredValues and limits
site_idpathstringYes
Body fieldTypeRequiredValues and limits
urlstringYes0 to 500 characters. For add and set_content_page
kindstringNopress, blog, listing, other, mention
live_onstringNoYYYY-MM-DD; for add (default today) and update

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/published-pages" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

PATCH /published-pages/{page_id}

Change the day a page went live.

Scope
scan:write
MCP tool
published_pages action update
ParameterInTypeRequiredValues and limits
page_idpathstringYesFor update and remove: from action list
Body fieldTypeRequiredValues and limits
live_onstringNoYYYY-MM-DD; for add (default today) and update

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl -X PATCH "https://app.scanfree.dev/api/v1/published-pages/00000000-0000-4000-8000-000000000006" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"live_on":"2026-11-20"}'

DELETE /published-pages/{page_id} ⚠

Stop tracking a page. Asks for confirmation first (see Two-step confirmation).

Scope
scan:write
MCP tool
published_pages action remove
ParameterInTypeRequiredValues and limits
page_idpathstringYesFor update and remove: from action list

Answers: 200 the tool’s answer; 409 needs_confirmation, then the same request with ScanFree-Confirm; errors as above. The answer’s fields are on the published_pages page.

Example
curl -X DELETE "https://app.scanfree.dev/api/v1/published-pages/00000000-0000-4000-8000-000000000006" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PUT /sites/{site_id}/content-page

The page of your own site you'd like AI to cite (empty url removes it).

Scope
scan:write
MCP tool
published_pages action set_content_page
ParameterInTypeRequiredValues and limits
site_idpathstringYes
Body fieldTypeRequiredValues and limits
urlstringNo0 to 500 characters. For add and set_content_page

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/content-page" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

Sites

GET /sites

Your businesses.

Scope
scan:read
MCP tool
sites action list

No parameters.

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.

Example
curl "https://app.scanfree.dev/api/v1/sites" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

POST /sites

Add a business.

Scope
scan:write
MCP tool
sites action add
Body fieldTypeRequiredValues and limits
urlstringYes0 to 500 characters
site_typestringYeslocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
citystringNo0 to 80 characters
namestringNo0 to 120 characters

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/sites" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com","site_type":"local_service"}'

PATCH /sites/{site_id}

Edit a business: name, city, kind, trade, your own facts (remove_facts takes some off).

Scope
scan:write
MCP tool
sites action update
ParameterInTypeRequiredValues and limits
site_idpathstringYes
Body fieldTypeRequiredValues and limits
namestringNo0 to 120 characters
citystringNo0 to 80 characters
site_typestringNolocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
tradestringNo0 to 60 characters
factsobjectNoKeys: name, description, phone, email, address, services, areas, hours, prices, credentials, profiles
remove_factsarray of stringNoat most 20 items. For update: own facts to remove, by key (e.g. ["phone", "hours"])

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.

Example
curl -X PATCH "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Plumbing"}'

PUT /sites/{site_id}/about

About your business, in the person's words.

Scope
scan:write
MCP tool
sites action save_about
ParameterInTypeRequiredValues and limits
site_idpathstringYes
Body fieldTypeRequiredValues and limits
entriesarray of objectYesat most 12 items

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.

Example
curl -X PUT "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/about" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries":[{"field":"sell","value":"Emergency plumbing, 24/7"}]}'

POST /sites/{site_id}/competitors

Add competitors, or switch them on and off.

Scope
scan:write
MCP tool
sites action set_competitors
ParameterInTypeRequiredValues and limits
site_idpathstringYes
Body fieldTypeRequiredValues and limits
competitorsarray of objectYesat most 20 items

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/competitors" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitors":[{"name":"Acme Plumbing","domain":"acmeplumbing.example"}]}'

GET /sites/{site_id}/brief

Every fact held about the business, with its source.

Scope
scan:read
ParameterInTypeRequiredValues and limits
site_idpathstringYes
formatquerystringNojson, markdown

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_brand_brief page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/brief?format=csv" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /sites/{site_id}/competitors

Who AI named instead, and your tracked competitors.

Scope
scan:read
ParameterInTypeRequiredValues and limits
site_idpathstringYesA site id from sites or get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_insights page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/competitors" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /sites/{site_id}/directory

The places worth being listed, and where you are.

Scope
scan:read
ParameterInTypeRequiredValues and limits
site_idpathstringYesA site id from sites or get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_insights page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/directory" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /sites/{site_id}/reviews

Review counts and ratings (never review text).

Scope
scan:read
ParameterInTypeRequiredValues and limits
site_idpathstringYesA site id from sites or get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_insights page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/reviews" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /sites/{site_id}/checks

The site's checks, each with its evidence tag.

Scope
scan:read
ParameterInTypeRequiredValues and limits
site_idpathstringYesA site id from sites or get_dashboard

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_insights page.

Example
curl "https://app.scanfree.dev/api/v1/sites/00000000-0000-4000-8000-000000000004/checks" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

Tools

POST /tools/reach

Start "Can AI reach you?" (no AI).

Scope
scan:read
MCP tool
site_tools
Body fieldTypeRequiredValues and limits
urlstringNo
site_idstringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_tools page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/tools/reach" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

GET /tools/reach/{run_id}

A reach run's lines.

Scope
scan:read
MCP tool
site_tools
ParameterInTypeRequiredValues and limits
run_idpathstringYesFor reach: the run_id from the first call

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_tools page.

Example
curl "https://app.scanfree.dev/api/v1/tools/reach/00000000-0000-4000-8000-000000000007" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /tools/robots

Which AI crawlers robots.txt lets in (no AI).

Scope
scan:read
MCP tool
site_tools
ParameterInTypeRequiredValues and limits
urlquerystringNo
site_idquerystringNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_tools page.

Example
curl "https://app.scanfree.dev/api/v1/tools/robots?url=example.com" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

Account

GET /account

Free scans left and email choices.

Scope
scan:read
MCP tool
account action get

No parameters.

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.

Example
curl "https://app.scanfree.dev/api/v1/account" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

PATCH /account/email-preferences

Change the email choices.

Scope
account:write
MCP tool
account action set_email_preferences
Body fieldTypeRequiredValues and limits
check_emailsstringNofull, short, off
alertsbooleanNo
adsbooleanNo

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.

Example
curl -X PATCH "https://app.scanfree.dev/api/v1/account/email-preferences" \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_emails":"short"}'

POST /account/exports

Make a zip of all the account's data.

Scope
account:write
MCP tool
account action start_export

No parameters.

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.

Example
curl -X POST "https://app.scanfree.dev/api/v1/account/exports" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /account/exports/latest

The latest data export.

Scope
scan:read
MCP tool
account action export_status

No parameters.

Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.

Example
curl "https://app.scanfree.dev/api/v1/account/exports/latest" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"