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.
https://app.scanfree.dev/api/v1Every 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.
Authorization: Bearer sf_live_YOUR_KEY| Scope | What it allows | Who has it |
|---|---|---|
scan:read | Read scans, orders, sites and the account. | Every key and sign-in |
scan:write | Start scans, set up orders, change phrases, sites, pages, claims, programs and share links. | Every key and sign-in |
order:write | Stop 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:write | Change 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.GETandDELETEtake their other parameters in the query;POST,PUTandPATCHtake a JSON object (Content-Type: application/json). - A parameter an endpoint doesn’t take is refused with
400 invalid_input, never ignored. - A
200answer is the tool’s own answer: it always hasstatus(ok, or a state such asrunning,queuedorcomplete) and oftenmessagein 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-factsis 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.
{
"error": {
"code": "not_found",
"message": "No such order on this account."
}
}| HTTP | code | What it means |
|---|---|---|
| 400 | invalid_input, invalid_questions | A parameter is missing, has the wrong type or value, or isn't one this endpoint takes. |
| 401 | missing_token, invalid_token | No key, or one that was revoked, has expired, or belongs to an unverified or blocked account. |
| 403 | forbidden, verify_email, revoked | The key lacks the endpoint's scope (see missing_scope), or the agent was revoked. |
| 404 | not_found | No such order, site, scan, phrase or page on this account. Another account's is not found too, never forbidden. |
| 409 | invalid_confirmation, not_available, refused, already_running, needs_review, paused | Valid, 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. |
| 429 | rate_limited, too_many_failures, limited, limit_reached, daily_limit | Too many requests (wait Retry-After seconds), or a product limit such as free scans this month, suggestions today or one export an hour. |
| 500 | internal_error | Our 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:
- The first call checks everything, changes nothing and answers
409with a plain summary and aconfirm_token. - Show the summary to the person. Only if they agree, send exactly the same request again with the header
ScanFree-Confirm: <confirm_token>(orconfirm_tokenin 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.
{
"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-RemainingandRateLimit-Policyfor the tighter of the two. Past the limit:429 rate_limitedwithRetry-Afterin 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 field | Type | Required | Values and limits |
|---|---|---|---|
url | string | Yes | The business website, for example example.com |
site_type | string | Yes | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | string | No | City and state for local types, e.g. Boise, Idaho |
questions | array of string | No | 1 to 10 items |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the start_scan page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
limit | query | integer | No | 1 to 50 |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the list_scans page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
scan_id | path | string | Yes | |
wait_seconds | query | integer | No | 0 to 25 |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_scan page.
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- MCP tool
explain_result
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
scan_id | path | string | Yes | A finished scan of this account |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the explain_result page.
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_linkactionget
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
scan_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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_linkactionon
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
scan_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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_linkactionoff
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
scan_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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- MCP tool
suggest_questions
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
url | query | string | Yes | |
site_type | query | string | Yes | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the suggest_questions page.
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- MCP tool
suggest_questions
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
url | query | string | Yes | |
site_type | query | string | Yes | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the suggest_questions page.
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- MCP tool
get_dashboard
No parameters.
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_dashboard page.
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 field | Type | Required | Values and limits |
|---|---|---|---|
preset | string | No | cheapest, recommended, premium. A ready-made order from the settings; other arguments given override its parts |
phrases | integer | No | 1 to 200 |
frequency | string | No | one_time, monthly, biweekly, weekly |
months | integer | No | 1 to 12 |
pay | string | No | once, monthly |
routes | array of string | No | at most 30 items |
research | integer | No | 0 to 100 |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the create_order page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_order page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the check_status page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_matrix page.
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- MCP tool
get_pages_to_beat
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | |
phrase_id | query | string | No | |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_pages_to_beat page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the list_actions page.
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- MCP tool
get_check_summary
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_check_summary page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_gap page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
format | query | string | Yes | csv, json, pdf |
check_id | query | string | No | One 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.
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- MCP tool
explain_result
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
check_id | path | string | Yes | A 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.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard (orders_waiting_for_setup) |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
site_id | string | No | |
url | string | No | |
site_type | string | No | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | string | No | |
name | string | No | The business name |
phrases | array of string | Yes | 1 to 200 items |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the order_setup page.
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_orderactionadd_note
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
text | string | Yes | 0 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.
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?"}'GET /orders/{order_id}/billing-link
Stripe's page to replace the card and see invoices.
- Scope
scan:read- MCP tool
manage_orderactionbilling_link
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the manage_order page.
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_orderactionstop
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An 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.
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_orderactionrequest_refund
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
note | string | No | 0 to 1000 characters. For request_refund: why, for the person at ScanFree |
stop | boolean | No | For 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.
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
addonsactionquote
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
kind | query | string | Yes | phrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add |
count | query | integer | No | 1 to 200. For phrases and checks |
route_key | query | string | No | 0 to 120 characters. For engine: an AI key (create_order's routes) |
competitors | query | integer | No | 0 to 100. For research (competitors a month) and backlinks (competitors besides your site) |
cadence | query | string | No | monthly, every_check. For backlinks |
size | query | integer | No | -9007199254740991 to 9007199254740991. For keywords: 100 or 500 |
months | query | integer | No | 2 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.
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
addonsactionapply
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
kind | string | Yes | phrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add |
count | integer | No | 1 to 200. For phrases and checks |
route_key | string | No | 0 to 120 characters. For engine: an AI key (create_order's routes) |
route_keys | array of string | No | at most 20 items. For recheck: AIs of this order (default all) |
competitors | integer | No | 0 to 100. For research (competitors a month) and backlinks (competitors besides your site) |
cadence | string | No | monthly, every_check. For backlinks |
size | integer | No | -9007199254740991 to 9007199254740991. For keywords: 100 or 500 |
keywords | array of string | No | at most 600 items. For keywords: your own list (optional) |
months | integer | No | 2 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.
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}'PUT /orders/{order_id}/backlink-competitors
The competitors the backlinks add-on checks.
- Scope
scan:write- MCP tool
addonsactionset_backlink_competitors
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
domains | array of string | Yes | at 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.
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_linkactionget
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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_linkactionon
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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_linkactionoff
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the share_link page.
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
phrasesactionlist
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the phrases page.
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
phrasesactionadd
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
text | string | Yes | 0 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.
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
phrasesactionreplace
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
phrase_id | path | string | Yes | For history, replace, retire, set_keywords: a phrase id from action list |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
text | string | Yes | 0 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.
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
phrasesactionretire
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
phrase_id | path | string | Yes | For 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.
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
phrasesactionhistory
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
phrase_id | path | string | Yes | For 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.
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
phrasesactionkeywords
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
limit | query | integer | No | 1 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.
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
phrasesactionset_keywords
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
keywords | array of string | Yes | at most 1000 items. For set_keywords |
phrase_id | string | No | For 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.
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
claimsactionlist
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.
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
claimsactionmark_wrong
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
claim | string | Yes | 0 to 300 characters |
polarity | string | Yes | positive, negative, neutral |
undo | boolean | No | For mark_wrong: take the mark off |
check_id | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.
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
claimsactionfixed_on
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
claim | string | Yes | 0 to 300 characters |
polarity | string | Yes | positive, negative, neutral |
fixed_on | string | Yes | For fixed_on: YYYY-MM-DD, or empty |
check_id | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.
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
claimsactionfacts
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
check_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.
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
claimsactionmark_fact
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
flag_id | path | string | Yes | For mark_fact: a flag_id from action facts |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
mark | string | Yes | wrong, right, clear. For mark_fact |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the claims page.
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
programsactionget
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the programs page.
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
programsactionset_item
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes | An order id from get_dashboard |
program | path | string | Yes | |
item | path | string | Yes | An item key from action get |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
status | string | Yes | todo, submitted, live |
url | string | No | 0 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.
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_pagesactionlist
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.
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_pagesactionadd
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
order_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
url | string | Yes | 0 to 500 characters. For add and set_content_page |
kind | string | No | press, blog, listing, other, mention |
live_on | string | No | YYYY-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.
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_pagesactionlist
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the published_pages page.
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_pagesactionadd
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
url | string | Yes | 0 to 500 characters. For add and set_content_page |
kind | string | No | press, blog, listing, other, mention |
live_on | string | No | YYYY-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.
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_pagesactionupdate
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
page_id | path | string | Yes | For update and remove: from action list |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
live_on | string | No | YYYY-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.
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_pagesactionremove
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
page_id | path | string | Yes | For 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.
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_pagesactionset_content_page
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
url | string | No | 0 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.
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
sitesactionlist
No parameters.
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.
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
sitesactionadd
| Body field | Type | Required | Values and limits |
|---|---|---|---|
url | string | Yes | 0 to 500 characters |
site_type | string | Yes | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | string | No | 0 to 80 characters |
name | string | No | 0 to 120 characters |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.
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
sitesactionupdate
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
name | string | No | 0 to 120 characters |
city | string | No | 0 to 80 characters |
site_type | string | No | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
trade | string | No | 0 to 60 characters |
facts | object | No | Keys: name, description, phone, email, address, services, areas, hours, prices, credentials, profiles |
remove_facts | array of string | No | at 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.
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
sitesactionsave_about
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
entries | array of object | Yes | at most 12 items |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.
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
sitesactionset_competitors
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes |
| Body field | Type | Required | Values and limits |
|---|---|---|---|
competitors | array of object | Yes | at most 20 items |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the sites page.
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- MCP tool
get_brand_brief
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes | |
format | query | string | No | json, markdown |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the get_brand_brief page.
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- MCP tool
site_insights
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes | A 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.
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- MCP tool
site_insights
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes | A 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.
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- MCP tool
site_insights
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes | A 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.
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- MCP tool
site_insights
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
site_id | path | string | Yes | A 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.
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 field | Type | Required | Values and limits |
|---|---|---|---|
url | string | No | |
site_id | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_tools page.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
run_id | path | string | Yes | For 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.
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
| Parameter | In | Type | Required | Values and limits |
|---|---|---|---|---|
url | query | string | No | |
site_id | query | string | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the site_tools page.
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
accountactionget
No parameters.
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.
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
accountactionset_email_preferences
| Body field | Type | Required | Values and limits |
|---|---|---|---|
check_emails | string | No | full, short, off |
alerts | boolean | No | |
ads | boolean | No |
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.
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
accountactionstart_export
No parameters.
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.
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
accountactionexport_status
No parameters.
Answers: 200 the tool’s answer; errors as above. The answer’s fields are on the account page.
curl "https://app.scanfree.dev/api/v1/account/exports/latest" \
-H "Authorization: Bearer sf_live_YOUR_KEY"