The iSuggest.ai API gives you the same audits, site scores and AI-directory publishing you get in the web app, over plain HTTPS and JSON. Everything you can do while signed in, you can script.
Base URL:https://isuggest.ai/api/v1
Format: JSON in, JSON out. Form-encoded bodies are also accepted.
Auth: one personal API key sent as a bearer token.
Versioned: this page documents release 1.1.0. Every release is kept, see the changelog.
Machine-readable: an OpenAPI 3.1 file you can import into Postman, Insomnia or a code generator.
Quickstart
Three steps, about a minute.
Get a key.Log in, open Account → API access and press Generate API key. Copy it straight away: it is shown once.
Treat a key like a password. Keep it in an environment variable or a secrets manager, never in client-side code, a public repository or a URL.
Keys are for servers and scripts you control. Do not embed one in a browser or mobile app.
Requests and responses
Every successful response wraps its payload in a data object. Every failure returns an error object with a human-readable message and the HTTP status.
// success
{ "data": { ... } }
// failure
{ "error": { "message": "You do not have access to this account.", "status": 403 } }
Timestamps are ISO 8601 in UTC, for example 2026-09-26T08:03:56+00:00.
IDs are opaque strings. Audits start with r_, directory snapshots with l_. Do not parse them.
Emails in paths must be URL-encoded: you@example.com becomes you%40example.com.
Missing data is null, never a made-up number. A score is null until there is enough real data to compute one.
Every response carries an X-API-Version header with the release that answered, such as 1.1.0.
Lists take a limit where they can be long, and return newest first.
Errors
Errors use standard HTTP status codes. The message is written for a person and is safe to show, but do not build logic on its wording. Branch on the status.
Status
Meaning
What to do
400 / 422
The request is missing something or a value is not valid.
Read the message, fix the input, retry.
401
No key, a wrong key, or a key that was replaced or revoked.
Check the Authorization header and that the key is still current.
402
Not enough credits for this action.
Top up on the account page, or lower the request (for example fewer pages in a scan).
403
The key is valid but this data or action is not yours.
You can only act on your own audits, websites and account.
404
The thing does not exist, or it is not yours to know about.
Check the id. Audits that are not yours also answer 404 or 403, by design.
409
A conflict, for example another account has already verified the domain.
Follow the message.
429
Too many audits too quickly (one per minute), or too many unverified websites on your account.
For audits, wait the number of seconds in the Retry-After header and try again. For websites, verify or release one, then add another.
500 / 502
Something failed on our side or in the audit engine, often because the audited site was unreachable.
Retry after a moment. If it persists, the message says why.
Credits and costs
Auditing a single page is free. Two actions spend credits from your account balance, the same as in the app:
Publishing to an AI directory costs a fixed number of credits per directory, charged once per audit and directory. Publishing the same audit again to the same directory is free.
Scanning a whole site costs a fixed number of credits per page actually crawled, and you are charged for pages stored, not pages requested.
Current prices are in GET /settings. Your balance and ledger are in GET /credits/{email}. An action you cannot afford is refused with 402 before anything is done or charged.
Privacy model
Your audits are private. Only your key can read them. There is no way to list or open anyone else's.
Directory snapshots are public. When you publish, a frozen copy becomes a permanent public page and is readable by anyone. Who published it is not shown to anyone but the publisher.
A page must score 90 or more to be published. Below that, publishing is refused with 422 and the message says what the page scored.
Sites you scan must be yours. Scanning and scoring a whole website need you to prove control of the domain first.
Versioning
The URL carries the major version (/api/v1). It changes only if we ever have to break something, and we would run the old major alongside the new one.
Inside a major version, every change ships as a numbered release (1.0.0, 1.1.0, and so on), each with its own dated changelog entry and its own frozen copy of this documentation.
Patch (1.0.1): fixes and clarifications, no new behaviour.
Minor (1.1.0): new endpoints, new optional parameters, new fields in responses. Your existing code keeps working, so ignore fields you do not recognise.
Major (v2): anything that could break an existing integration.
Read the current release from GET /health or the X-API-Version header. Browse older documentation from the changelog.
Fair use
One audit per minute. Each account can run one single-page audit per minute, across the website, the API and every key it owns, because every audit uses the audit engine and Google services that have rate limits of their own. This applies to POST /reports and POST /reports/{id}/refresh. A request over the limit is refused with 429 and a Retry-After header holding the seconds to wait, and it does not use up your minute. An audit that fails because the page could not be reached does count, since the audit engine was still called. Site scans, publishing and reading data are not affected by it.
Beyond that, please keep concurrency low and cache results instead of re-auditing the same page. We may throttle or suspend keys that put the service at risk, and will say so here and in the changelog. Audit only pages you have the right to audit.
Service
A single unauthenticated call for monitoring and for discovering the current release.
GET/healthNo key needed
Service status and current API release
Use this for uptime checks and to read which release of the API is live. No key needed.
Run a page audit and read your audits back. Audits are private to your account.
POST/reportsAPI key
Run an audit
Crawls one public page, analyses it and stores the audit under your account. It is free. It usually takes a few seconds, so set a generous client timeout (60 seconds is sensible). Each account can run one audit per minute (see Fair use).
The page must be a public http or https address. Private-network addresses and URLs with credentials are refused. Re-auditing a URL you have audited before replaces the earlier audit.
Parameters
Name
In
Type
Description
urlrequired
body
string
The full address of the page to audit, for example https://example.com/pricing.
Trimmed for readability. Each page object also carries headings, links, images, Open Graph and Twitter tags, structured data, text statistics and warnings. The audit's score is data.pages[0].seo_analysis.overall_score.
Errors
Status
Message
422
Enter a public http or https URL. Private-network and credentialed URLs are not allowed.
429
You can run one audit per minute. Try again in 42 seconds.
500
Audit failed: the page could not be reached or analysed (the message says why).
401
A valid bearer token is required.
GET/reportsAPI key
List your audits
Your audits, newest first, as light summaries with the score and issue counts. Fetch one audit by id for the full detail. An audit that was run before per-page scoring existed has score: null.
Trimmed for readability. Each page object also carries headings, links, images, Open Graph and Twitter tags, structured data, text statistics and warnings.
Errors
Status
Message
403
You do not have access to this report.
404
Report not found.
POST/reports/{id}/refreshAPI key
Re-crawl an audit in place
Runs the audit again on the same URL and replaces the stored result, keeping the same id. Free, and counts toward the one-audit-a-minute limit.
Parameters
Name
In
Type
Description
idrequired
path
string
The audit id.
Example request
curl -s -X POST https://isuggest.ai/api/v1/reports/r_a812d5be44a5/refresh \
-H "Authorization: Bearer $ISUGGEST_API_KEY"
Trimmed for readability. Each page object also carries headings, links, images, Open Graph and Twitter tags, structured data, text statistics and warnings.
Errors
Status
Message
403
You do not have access to this report.
404
Report not found.
429
You can run one audit per minute. Try again in 42 seconds.
500
Audit failed: the page could not be reached or analysed.
Websites
Add a website, prove you control it, then scan it and read its GEO score. Scanning and scoring are for verified sites only, so nobody can crawl or rate a domain they do not own.
GET/websitesAPI key
List your websites
The websites on your account, including ones you have added but not yet verified. For a site you own, the record includes its cached score. For a site you have only claimed, you see your own claim and nothing about whoever else may have added it.
Registers your interest in a domain and returns the verification token and the three ways to prove you control it. Adding a site does not make you its owner. Two accounts can add the same domain, and only whoever proves control gets it.
Use a bare domain such as example.com. A full URL is accepted and reduced to its host.
{
"data": {
"website": {
"host": "example.com",
"display_host": "example.com",
"status": "pending",
"verified_at": null,
"released_at": null,
"public_scorecard": false,
"created_at": "2026-09-26T08:03:42+00:00",
"updated_at": "2026-09-26T08:03:42+00:00",
"your_token": "38bfed7b031704f4b64945d5dfad7515",
"your_claim_at": "2026-09-26T08:03:42+00:00",
"is_owner": false,
"claim_count": 1
},
"instructions": {
"meta": {
"label": "HTML meta tag",
"hint": "Paste this inside the <head> of your home page, then press Verify.",
"snippet": "<meta name=\"isuggest-site-verification\" content=\"38bfed7b031704f4b64945d5dfad7515\">"
},
"file": {
"label": "HTML file",
"hint": "Upload a file at this path containing the token on its own line.",
"snippet": "/isuggest-verification-38bfed7b031704f4b64945d5dfad7515.txt"
},
"dns": {
"label": "DNS TXT record",
"hint": "Add this TXT record at your DNS provider.",
"snippet": "_isuggest.example.com TXT \"isuggest-site-verification=38bfed7b031704f4b64945d5dfad7515\""
}
}
}
}
Errors
Status
Message
403
You do not have access to this website.
404
Website not found.
POST/websites/{host}/verifyAPI key
Check the proof and claim ownership
Looks for your token on the site, by any of the three methods. If it finds it, you become the verified owner. If not, the response lists every place it looked and what it saw, so you can see exactly what to fix. A failed check is a normal 200 with ok: false, not an error.
Publish the token first (meta tag on the home page, a file at the given path, or the DNS TXT record), then call this. DNS changes can take a while to spread.
Parameters
Name
In
Type
Description
hostrequired
path
string
The domain to verify.
Example request
curl -s -X POST https://isuggest.ai/api/v1/websites/example.com/verify \
-H "Authorization: Bearer $ISUGGEST_API_KEY"
Response 200
{
"data": {
"ok": false,
"outcome": "not_found",
"message": "We reached example.com but could not find your verification token. Check that the tag is on the home page itself and visible without JavaScript, then try again.",
"attempts": [
{
"method": "dns",
"source": "_isuggest.example.com",
"result": "not found"
},
{
"method": "meta",
"source": "https://example.com/",
"result": "tag not found"
},
{
"method": "file",
"source": "https://example.com/isuggest-verification-38bfed7b031704f4b64945d5dfad7515.txt",
"result": "HTTP 404"
}
],
"website": {
"host": "example.com",
"display_host": "example.com",
"status": "pending",
"verified_at": null,
"released_at": null,
"public_scorecard": false,
"created_at": "2026-09-26T08:03:42+00:00",
"updated_at": "2026-09-26T08:03:42+00:00",
"your_token": "38bfed7b031704f4b64945d5dfad7515",
"your_claim_at": "2026-09-26T08:03:42+00:00",
"is_owner": false,
"claim_count": 1
}
}
}
On success, ok is true, outcome is verified, the website is yours, and adopted_reports counts earlier audits of the domain that were attached to you.
Errors
Status
Message
409
Add this website to your account before verifying it.
409
Another account verified this domain first. Contact support if you believe this is wrong.
409
This domain was released very recently and is on a short hold. Try again in 24 hours.
404
Website not found.
POST/websites/{host}/releaseAPI key
Release a website from your account
Drops your claim or ownership. A domain you owned goes on a short hold before anyone else can verify it.
Parameters
Name
In
Type
Description
hostrequired
path
string
The domain to release.
Example request
curl -s -X POST https://isuggest.ai/api/v1/websites/example.com/release \
-H "Authorization: Bearer $ISUGGEST_API_KEY"
Crawls your site's pages, stores each as its own audit, and recomputes the site score from all of them. Only the verified owner can scan. You are charged for pages actually stored, at the per-page price in GET /settings, and a scan is limited to what your balance can pay for.
Parameters
Name
In
Type
Description
hostrequired
path
string
A domain you have verified.
max_pages
body
integer
How many pages to crawl. Default and maximum are set in site_scan_max_pages.
Verify that you control this website before scanning it.
402
A site scan costs 1 credit(s) per page and your balance is 0.
502
The audit engine could not crawl this site: (reason).
POST/websites/{host}/scoreAPI key
Recompute the site score
Recomputes the site's GEO score now, from your stored audits of the domain plus a fresh look at its robots.txt, sitemap and home page. It does not crawl new pages and it is free. Use scan to add pages first.
Parameters
Name
In
Type
Description
hostrequired
path
string
A domain on your account.
Example request
curl -s -X POST https://isuggest.ai/api/v1/websites/example.com/score \
-H "Authorization: Bearer $ISUGGEST_API_KEY"
The last computed score, the change since the previous one, and the score history (one point per day). It never reaches out to the site, so it is fast and safe to poll. stale is true when the score is old enough that you may want to recompute it.
Reading the score object:state is graded when there are enough audited pages (at least 3) to grade the domain, provisional when there are fewer, and unreachable when the site could not be reached. Unless it is graded, score is null and the pillars show only what could be measured. We do not show a number we cannot stand behind. See How scoring works for the pillars and checks.
Trimmed. score is null if the site has never been scored.
Errors
Status
Message
403
You do not have access to this website.
404
Website not found.
GET/websites/{host}/reportAPI key
Combined site report
One report for the whole domain: the score, totals, every finding rolled up across pages with the pages it affects, findings by category, the pages ranked weakest first, and what passed. Built from stored audits only.
Publish a good audit as a permanent public snapshot in the Gemini, ChatGPT or Claude directory, in HTML, JSON and Markdown, for AI crawlers to read. Providers: gemini, chatgpt, claude.
POST/submissionsAPI keySpends credits
Publish an audit to an AI directory
Freezes one of your audits as a public snapshot. Three rules:
The audit must be yours.
The audited page must score 90 or more. Below that, or with no score, it is refused with 422 and the message says what the page scored. Fix the issues and audit again.
It costs credits, charged once per audit and directory. Publishing the same audit to the same directory again returns the existing snapshot and charges nothing.
A snapshot is permanent and public. It cannot be edited or removed by the API. The response includes what was charged and your new balance.
The full snapshot is returned to you, its publisher, including the frozen report. It is trimmed here.
Errors
Status
Message
422
This page scores 83. A page needs 90 or more to be published to an AI directory. Fix the issues in the report, then audit it again.
422
This audit has no score yet, so it cannot be published. Re-audit the page to get one; a page needs 90 or more to go into an AI directory.
402
Publishing to gemini costs 10 credit(s) and your balance is 0.
403
You may only publish audits you ran.
404
Report not found.
GET/submissions?owner={email}API key
List the snapshots you published
Snapshots published by your account, newest first. This is the only list that shows who published. Passing someone else's email does not work: a key is always limited to its own account.
Public snapshots, newest first, optionally narrowed to one directory or to one source audit. This is public information: it never includes who published.
Parameters
Name
In
Type
Description
provider
query
string
Only snapshots in this directory: gemini, chatgpt or claude.
report_id
query
string
Only snapshots made from this audit. Returned keyed by directory.
Trimmed. The public web page for a snapshot is at https://isuggest.ai/ai-directory/{provider}/{id}, with .json and .md versions.
Errors
Status
Message
404
Snapshot not found.
Account
Your credit balance and the current prices.
GET/credits/{email}API key
Your credit balance and ledger
Your balance and the most recent ledger entries, newest first. Every credit added or spent is recorded, with the reason and the balance afterwards. You can only read your own.
What things cost right now. Prices can change between releases of the site without a new API release, so read them from here instead of hard-coding them.
submission_cost: credits to publish to each directory.
site_scan_cost_per_page: credits per page crawled in a scan.
site_scan_max_pages: the most pages one scan can crawl.
signup_bonus_credits: credits a new account starts with.
Stuck, or found something in the documentation that does not match what the API does? Write to us from the contact page and include the request you sent, the response you got, and the value of the X-API-Version header.
