{ "openapi": "3.1.0", "info": { "title": "iSuggest.ai API", "version": "1.1.0", "summary": "Audit pages, verify and score your sites, and publish to the AI directories from your own code.", "description": "Documentation: https://isuggest.ai/developers/api/1.1.0" }, "servers": [ { "url": "https://isuggest.ai/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Service", "description": "A single unauthenticated call for monitoring and for discovering the current release." }, { "name": "Audits", "description": "Run a page audit and read your audits back. Audits are private to your account." }, { "name": "Websites", "description": "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." }, { "name": "AI directory", "description": "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." }, { "name": "Account", "description": "Your credit balance and the current prices." }, { "name": "Blog", "description": "Read the iSuggest.ai blog as data." } ], "paths": { "/health": { "get": { "operationId": "get_health", "summary": "Service status and current API release", "description": "Use this for uptime checks and to read which release of the API is live. No key needed.", "tags": [ "Service" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "status": "ok", "version": "v1", "release": "1.1.0" } } } } } } } }, "/reports": { "post": { "operationId": "create_report", "summary": "Run an audit", "description": "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).\nThe 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.", "tags": [ "Audits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The full address of the page to audit, for example https://example.com/pricing." } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "report": { "id": "r_a812d5be44a5", "url": "https://example.com", "normalized_url": "https://example.com/", "domain": "example.com", "owner_email": "you@example.com", "created_at": "2026-09-26T08:03:56+00:00", "data": { "root_url": "https://example.com", "pages_crawled": 1, "summary": { "status_codes": { "200": 1 }, "errors": [], "median_word_count": 21 }, "pages": [ { "url": "https://example.com", "status_code": 200, "title": "Example Domain", "meta_description": "", "seo_analysis": { "overall_score": 83, "category_scores": { "indexability": 82, "metadata": 77, "content": 72, "technical": 95, "social": 90, "accessibility": 100 }, "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "issues": [ { "id": "missing_canonical", "category": "indexability", "severity": "high", "title": "Canonical URL is missing", "evidence": "canonical is empty", "recommendation": "Add a self-referencing canonical URL to declare the preferred address.", "penalty": 12 } ], "passed_checks": [ "..." ] } } ], "performance": null }, "summary": { "status_codes": { "200": 1 }, "errors": [] }, "fallback": false, "note": null } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Enter a public http or https URL. Private-network and credentialed URLs are not allowed.", "status": 422 } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You can run one audit per minute. Try again in 42 seconds.", "status": 429 } } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Audit failed: the page could not be reached or analysed (the message says why).", "status": 500 } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } }, "get": { "operationId": "list_reports", "summary": "List your audits", "description": "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.", "tags": [ "Audits" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many to return. Default 5, maximum 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "reports": [ { "id": "r_a812d5be44a5", "url": "https://example.com", "normalized_url": "https://example.com/", "domain": "example.com", "owner_email": "you@example.com", "created_at": "2026-09-26T08:03:56+00:00", "updated_at": null, "fallback": false, "note": null, "public": false, "score": 83, "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "pages_crawled": 1 } ] } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } } }, "/reports/history": { "get": { "operationId": "reports_history", "summary": "Your audits grouped by domain", "description": "The same summaries as the list, grouped under each domain, for showing how a site has changed over time.", "tags": [ "Audits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "domains": { "example.com": [ { "id": "r_a812d5be44a5", "url": "https://example.com", "normalized_url": "https://example.com/", "domain": "example.com", "owner_email": "you@example.com", "created_at": "2026-09-26T08:03:56+00:00", "updated_at": null, "fallback": false, "note": null, "public": false, "score": 83, "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "pages_crawled": 1 } ] } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } } }, "/reports/{id}": { "get": { "operationId": "get_report", "summary": "Get one audit in full", "description": "The complete audit: every page analysed, every issue with its evidence and recommendation, and the passed checks. You can only read your own audits.", "tags": [ "Audits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audit id, from POST /reports or GET /reports.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "report": { "id": "r_a812d5be44a5", "url": "https://example.com", "normalized_url": "https://example.com/", "domain": "example.com", "owner_email": "you@example.com", "created_at": "2026-09-26T08:03:56+00:00", "data": { "root_url": "https://example.com", "pages_crawled": 1, "summary": { "status_codes": { "200": 1 }, "errors": [], "median_word_count": 21 }, "pages": [ { "url": "https://example.com", "status_code": 200, "title": "Example Domain", "meta_description": "", "seo_analysis": { "overall_score": 83, "category_scores": { "indexability": 82, "metadata": 77, "content": 72, "technical": 95, "social": 90, "accessibility": 100 }, "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "issues": [ { "id": "missing_canonical", "category": "indexability", "severity": "high", "title": "Canonical URL is missing", "evidence": "canonical is empty", "recommendation": "Add a self-referencing canonical URL to declare the preferred address.", "penalty": 12 } ], "passed_checks": [ "..." ] } } ], "performance": null }, "summary": { "status_codes": { "200": 1 }, "errors": [] }, "fallback": false, "note": null } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this report.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Report not found.", "status": 404 } } } } } } } }, "/reports/{id}/refresh": { "post": { "operationId": "refresh_report", "summary": "Re-crawl an audit in place", "description": "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.", "tags": [ "Audits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audit id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "report": { "id": "r_a812d5be44a5", "url": "https://example.com", "normalized_url": "https://example.com/", "domain": "example.com", "owner_email": "you@example.com", "created_at": "2026-09-26T08:03:56+00:00", "data": { "root_url": "https://example.com", "pages_crawled": 1, "summary": { "status_codes": { "200": 1 }, "errors": [], "median_word_count": 21 }, "pages": [ { "url": "https://example.com", "status_code": 200, "title": "Example Domain", "meta_description": "", "seo_analysis": { "overall_score": 83, "category_scores": { "indexability": 82, "metadata": 77, "content": 72, "technical": 95, "social": 90, "accessibility": 100 }, "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "issues": [ { "id": "missing_canonical", "category": "indexability", "severity": "high", "title": "Canonical URL is missing", "evidence": "canonical is empty", "recommendation": "Add a self-referencing canonical URL to declare the preferred address.", "penalty": 12 } ], "passed_checks": [ "..." ] } } ], "performance": null }, "summary": { "status_codes": { "200": 1 }, "errors": [] }, "fallback": false, "note": null, "updated_at": "2026-09-26T09:12:40+00:00" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this report.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Report not found.", "status": 404 } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You can run one audit per minute. Try again in 42 seconds.", "status": 429 } } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Audit failed: the page could not be reached or analysed.", "status": 500 } } } } } } } }, "/websites": { "get": { "operationId": "list_websites", "summary": "List your websites", "description": "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.", "tags": [ "Websites" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "websites": [ { "host": "example.com", "display_host": "example.com", "owner_email": "you@example.com", "status": "verified", "verified_at": "2026-09-26T08:05:29+00:00", "verified_method": "meta", "released_at": null, "public_scorecard": false, "created_at": "2026-09-26T08:03:42+00:00", "updated_at": "2026-09-26T08:05:31+00:00", "score": "(the score object, see \"The score object\")" } ] } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } }, "post": { "operationId": "add_website", "summary": "Add a website", "description": "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.\nUse a bare domain such as example.com. A full URL is accepted and reduced to its host.", "tags": [ "Websites" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "description": "The domain to add, for example example.com." } }, "required": [ "host" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "ok": true, "outcome": "pending", "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 of your home page, then press Verify.", "snippet": "" }, "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\"" } } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "That does not look like a website address we can verify. Use a public domain such as example.com.", "status": 422 } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Another account has already verified this domain. If you own it, contact support and we will check the claim.", "status": 409 } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You have too many unverified websites already. Verify or remove one before adding another.", "status": 429 } } } } } } } }, "/websites/{host}": { "get": { "operationId": "get_website", "summary": "Get one website and its verification steps", "description": "The website record and, while you hold an unverified claim, the exact tag, file or DNS record to publish to prove ownership. The token is yours alone.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "The domain, for example example.com.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 of your home page, then press Verify.", "snippet": "" }, "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\"" } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this website.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } } }, "/websites/{host}/verify": { "post": { "operationId": "verify_website", "summary": "Check the proof and claim ownership", "description": "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.\nPublish 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.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "The domain to verify.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Add this website to your account before verifying it.", "status": 409 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } } }, "/websites/{host}/release": { "post": { "operationId": "release_website", "summary": "Release a website from your account", "description": "Drops your claim or ownership. A domain you owned goes on a short hold before anyone else can verify it.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "The domain to release.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "ok": true, "outcome": "released", "website": { "host": "example.com", "status": "released", "released_at": "2026-09-26T08:05:33+00:00" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have a claim on that website.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } } }, "/websites/{host}/scan": { "post": { "operationId": "scan_website", "summary": "Scan several pages of a verified site", "description": "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.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "A domain you have verified.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_pages": { "type": "integer", "description": "How many pages to crawl. Default and maximum are set in site_scan_max_pages." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "ok": true, "outcome": "scanned", "pages_scanned": 10, "pages_requested": 10, "credits_charged": 10, "balance": 14, "score": { "version": "1.0", "host": "example.com", "computed_at": "2026-09-26T08:05:31+00:00", "state": "provisional", "score": null, "grade": null, "grade_label": null, "pages_evaluated": 1, "pillars": { "page_health": { "key": "page_health", "label": "Page health", "weight": 55, "score": 83, "available": true }, "site_technical": { "key": "site_technical", "label": "Site technical", "weight": 20, "score": 70, "available": true, "checks": [ "..." ] } }, "caps_applied": [], "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "top_issues": [ "..." ], "message": "Audited 1 of at least 3 pages needed for a domain grade. The page scores below are real; the domain score is not meaningful yet.", "signals": [ "..." ] }, "website": { "host": "example.com", "display_host": "example.com", "owner_email": "you@example.com", "status": "verified", "verified_at": "2026-09-26T08:05:29+00:00", "verified_method": "meta", "released_at": null, "public_scorecard": false, "created_at": "2026-09-26T08:03:42+00:00", "updated_at": "2026-09-26T08:05:31+00:00", "score": "(the score object, see \"The score object\")" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Verify that you control this website before scanning it.", "status": 403 } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A site scan costs 1 credit(s) per page and your balance is 0.", "status": 402 } } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "The audit engine could not crawl this site: (reason).", "status": 502 } } } } } } } }, "/websites/{host}/score": { "post": { "operationId": "score_website", "summary": "Recompute the site score", "description": "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.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "A domain on your account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "ok": true, "outcome": "scored", "score": { "version": "1.0", "host": "example.com", "computed_at": "2026-09-26T08:05:31+00:00", "state": "provisional", "score": null, "grade": null, "grade_label": null, "pages_evaluated": 1, "pillars": { "page_health": { "key": "page_health", "label": "Page health", "weight": 55, "score": 83, "available": true }, "site_technical": { "key": "site_technical", "label": "Site technical", "weight": 20, "score": 70, "available": true, "checks": [ "..." ] } }, "caps_applied": [], "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "top_issues": [ "..." ], "message": "Audited 1 of at least 3 pages needed for a domain grade. The page scores below are real; the domain score is not meaningful yet.", "signals": [ "..." ] }, "delta": null, "history": [ { "date": "2026-09-26", "state": "provisional", "score": null, "grade": null, "pages_evaluated": 1 } ], "website": { "host": "example.com", "display_host": "example.com", "owner_email": "you@example.com", "status": "verified", "verified_at": "2026-09-26T08:05:29+00:00", "verified_method": "meta", "released_at": null, "public_scorecard": false, "created_at": "2026-09-26T08:03:42+00:00", "updated_at": "2026-09-26T08:05:31+00:00", "score": "(the score object, see \"The score object\")" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this website.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } }, "get": { "operationId": "get_website_score", "summary": "Read the cached site score and its history", "description": "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.\nReading 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.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "A domain on your account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "score": { "version": "1.0", "host": "example.com", "computed_at": "2026-09-26T08:05:31+00:00", "state": "provisional", "score": null, "grade": null, "grade_label": null, "pages_evaluated": 1, "pillars": { "page_health": { "key": "page_health", "label": "Page health", "weight": 55, "score": 83, "available": true }, "site_technical": { "key": "site_technical", "label": "Site technical", "weight": 20, "score": 70, "available": true, "checks": [ "..." ] } }, "caps_applied": [], "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "top_issues": [ "..." ], "message": "Audited 1 of at least 3 pages needed for a domain grade. The page scores below are real; the domain score is not meaningful yet.", "signals": [ "..." ] }, "delta": null, "updated_at": "2026-09-26T08:05:31+00:00", "stale": false, "history": [ { "date": "2026-09-26", "state": "provisional", "score": null, "grade": null, "pages_evaluated": 1 } ] } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this website.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } } }, "/websites/{host}/report": { "get": { "operationId": "get_website_report", "summary": "Combined site report", "description": "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.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "A domain on your account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "report": { "host": "example.com", "generated_at": "2026-09-26T08:05:33+00:00", "criteria_version": "1.0", "score": { "version": "1.0", "host": "example.com", "computed_at": "2026-09-26T08:05:31+00:00", "state": "provisional", "score": null, "grade": null, "grade_label": null, "pages_evaluated": 1, "pillars": { "page_health": { "key": "page_health", "label": "Page health", "weight": 55, "score": 83, "available": true }, "site_technical": { "key": "site_technical", "label": "Site technical", "weight": 20, "score": 70, "available": true, "checks": [ "..." ] } }, "caps_applied": [], "issue_counts": { "critical": 0, "high": 3, "medium": 1, "low": 4 }, "top_issues": [ "..." ], "message": "Audited 1 of at least 3 pages needed for a domain grade. The page scores below are real; the domain score is not meaningful yet.", "signals": [ "..." ] }, "totals": [ "..." ], "findings": [ "..." ], "by_category": [ "..." ], "pages": [ "..." ], "passed": [ "..." ] } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this website.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Website not found.", "status": 404 } } } } } } } }, "/websites/{host}/public": { "post": { "operationId": "set_website_public", "summary": "Show or hide the public scorecard", "description": "Your score is private by default. Turn this on to let people with the link see a public scorecard. Only the verified owner can change it.", "tags": [ "Websites" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "A domain you own.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public": { "type": "boolean", "description": "true to publish the scorecard, false to hide it." } }, "required": [ "public" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "ok": true, "outcome": "updated", "website": { "host": "example.com", "display_host": "example.com", "owner_email": "you@example.com", "status": "verified", "verified_at": "2026-09-26T08:05:29+00:00", "verified_method": "meta", "released_at": null, "public_scorecard": false, "created_at": "2026-09-26T08:03:42+00:00", "updated_at": "2026-09-26T08:05:31+00:00", "score": "(the score object, see \"The score object\")" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Only the verified owner can change that.", "status": 403 } } } } } } } }, "/submissions": { "post": { "operationId": "publish_submission", "summary": "Publish an audit to an AI directory", "description": "Freezes one of your audits as a public snapshot. Three rules:\nThe audit must be yours.\nThe 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.\nIt costs credits, charged once per audit and directory. Publishing the same audit to the same directory again returns the existing snapshot and charges nothing.\nA snapshot is permanent and public. It cannot be edited or removed by the API. The response includes what was charged and your new balance.", "tags": [ "AI directory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_id": { "type": "string", "description": "The audit id." }, "provider": { "type": "string", "description": "One of gemini, chatgpt, claude." } }, "required": [ "report_id", "provider" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "submission": { "id": "l_1eb2e88fe918221b2352", "provider": "gemini", "source_report_id": "r_a812d5be44a5", "source_url": "https://example.com", "submitted_at": "2026-09-26T08:04:11+00:00", "snapshot_sha256": "1f964f1ee8b8c6504cc61c3f9423e0dd08d57ab2bf25ed14855dabc125c75cca", "title": "Example Domain", "description": "", "score": 94, "knowledge": { "captured": false }, "submitted_by": "you@example.com", "target_crawlers": [ "Google-Extended", "Googlebot" ], "report": [ "..." ] }, "credits_charged": 10, "balance": 15 } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "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.", "status": 422 } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Publishing to gemini costs 10 credit(s) and your balance is 0.", "status": 402 } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You may only publish audits you ran.", "status": 403 } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Report not found.", "status": 404 } } } } } } }, "get": { "operationId": "list_submissions", "summary": "Browse published snapshots", "description": "Public snapshots, newest first, optionally narrowed to one directory or to one source audit. This is public information: it never includes who published.", "tags": [ "AI directory" ], "parameters": [ { "name": "provider", "in": "query", "required": false, "description": "Only snapshots in this directory: gemini, chatgpt or claude.", "schema": { "type": "string" } }, { "name": "report_id", "in": "query", "required": false, "description": "Only snapshots made from this audit. Returned keyed by directory.", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "description": "Your own email address, URL-encoded.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "submissions": [ { "id": "l_1eb2e88fe918221b2352", "provider": "gemini", "source_report_id": "r_a812d5be44a5", "source_url": "https://example.com", "submitted_at": "2026-09-26T08:04:11+00:00", "snapshot_sha256": "1f964f1ee8b8c6504cc61c3f9423e0dd08d57ab2bf25ed14855dabc125c75cca", "title": "Example Domain", "description": "", "score": 94, "knowledge": { "captured": false } } ] } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } } }, "/submissions/{provider}/{id}": { "get": { "operationId": "get_submission", "summary": "Get one snapshot", "description": "A single published snapshot with its frozen report. Anyone can read a snapshot, and only its publisher sees the submitted_by field.", "tags": [ "AI directory" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "gemini, chatgpt or claude.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The snapshot id, starting with l_.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "submission": { "id": "l_1eb2e88fe918221b2352", "provider": "gemini", "source_report_id": "r_a812d5be44a5", "source_url": "https://example.com", "submitted_at": "2026-09-26T08:04:11+00:00", "snapshot_sha256": "1f964f1ee8b8c6504cc61c3f9423e0dd08d57ab2bf25ed14855dabc125c75cca", "title": "Example Domain", "description": "", "score": 94, "knowledge": { "captured": false }, "target_crawlers": [ "Google-Extended", "Googlebot" ], "report": [ "..." ] } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Snapshot not found.", "status": 404 } } } } } } } }, "/credits/{email}": { "get": { "operationId": "get_credits", "summary": "Your credit balance and ledger", "description": "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.", "tags": [ "Account" ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "Your own email address, URL-encoded.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many ledger entries. Default 50, maximum 200.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "balance": 15, "ledger": [ { "id": "cr_bf25457b09baeb8f", "email": "you@example.com", "delta": -10, "reason": "AI directory submission", "ref_type": "report", "ref_id": "r_a812d5be44a5", "balance_after": 15, "actor": "you@example.com", "created_at": "2026-09-26T08:04:11+00:00" } ] } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "You do not have access to this account.", "status": 403 } } } } } } } }, "/settings": { "get": { "operationId": "get_settings", "summary": "Current prices and limits", "description": "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.\nsubmission_cost: credits to publish to each directory.\nsite_scan_cost_per_page: credits per page crawled in a scan.\nsite_scan_max_pages: the most pages one scan can crawl.\nsignup_bonus_credits: credits a new account starts with.", "tags": [ "Account" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "settings": { "signup_bonus_credits": 20, "submission_cost": { "gemini": 10, "chatgpt": 10, "claude": 10 }, "site_scan_cost_per_page": 1, "site_scan_max_pages": 30, "updated_at": null } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } } }, "/blog": { "get": { "operationId": "list_blog", "summary": "List published posts", "description": "Published posts, newest first.", "tags": [ "Blog" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many posts. Default 50, maximum 200.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "posts": [ { "slug": "what-is-geo", "title": "What Is GEO?", "excerpt": "A plain-English introduction to Generative Engine Optimization.", "published": true, "published_at": "2026-09-01T06:00:00+00:00", "body_html": "

...

" } ] } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "A valid bearer token is required.", "status": 401 } } } } } } } }, "/blog/{slug}": { "get": { "operationId": "get_blog_post", "summary": "Get one post", "description": "One published post by its slug.", "tags": [ "Blog" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The post slug, from the list or its web address.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "post": { "slug": "what-is-geo", "title": "What Is GEO?", "body_html": "

...

" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Post not found.", "status": 404 } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your personal API key, from https://isuggest.ai/account/api (starts with isk_)." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "message", "status" ] } }, "required": [ "error" ] } } } }