API Reference

Build on verifiable AI visibility scores.

Signal Scanner is the independent AI-visibility measurement layer. The connector API gives you programmatic access to scores, citations, and fix items derived from real AI engine responses. Every number traces to a stored response, and empty states are reported honestly when no scan data exists.

Authentication

Every connector data endpoint requires an API key. Two header formats are accepted; use whichever fits your HTTP client.

Authorization: Bearer ssk_your_api_key
x-api-key: ssk_your_api_key

OAuth access tokens (with the sat_ prefix) are also accepted for platform integrations. Requests without a valid key receive a 401.

Getting access

Connector access is a Pro capability. Pro members generate an API key inside the dashboard under Settings. For reporting platform and agency integrations, talk to our team and we will set up the connection with you.

Base URLhttps://signalscanner.io

Schema versioning

Every connector data endpoint returns a schema_version field at the top level of the JSON body, and the same value in the X-Signal-Schema-Version response header, so you can check the version from headers without parsing the body. Each endpoint is versioned independently.

The policy your integration can rely on:

  • Additive changes (new fields appearing) do not change the version. Build your parser to ignore fields it does not recognize.
  • Removing a field, renaming a field, or changing a field's type is a breaking change. It bumps the version and comes with a deprecation notice.
  • Read the version on every response to detect changes explicitly.

Endpoints

GET/api/connector/brands

Lists the brands your API key can query, with the IDs and locations you need for every other endpoint.

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
brandsarrayBrands owned by the account the key belongs to.
brands[].idnumberBrand ID. Use this as :brandId in the other endpoints.
brands[].namestringBrand display name.
brands[].domainstring | nullPrimary domain of the brand. Null when no website is set.
brands[].locationsstring[]All locations configured for the brand. The array index is the locationIndex value accepted by the other endpoints.
GET/api/connector/signals/:brandId

Returns the composite Signal Score and the per-signal breakdown from the latest stored scan run for the brand and location.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0 (the primary location).

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
hasDatabooleanFalse when no stored scan exists for this brand and location. No fabricated data is ever returned.
runIdnumberID of the scan run this data comes from.
runCreatedAtstringTimestamp of the scan run.
compositenumber | nullComposite Signal Score from 0 to 100.
bandstring | nullBand label for the composite score.
signalsarrayThe six measured signals.
signals[].idstringStable signal identifier.
signals[].namestringSignal display name.
signals[].scorenumberSignal score.
signals[].weightnumberWeight of the signal in the composite.
signals[].bandstringBand label for the signal.
signals[].statusstringStatus label for the signal.
signals[].componentsarrayComponent scores inside the signal. Each has id, label, score, and points.

Empty state (no stored scan yet)

{ "schema_version": "1.0", "hasData": false }
GET/api/connector/citations/:brandId

Returns every domain that appeared as a cited source across the engine responses in the latest scan, ranked by citation count.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0.

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
hasAuditbooleanFalse when no stored scan exists for this brand and location.
runIdnumberID of the scan run this data comes from.
runCreatedAtstringTimestamp of the scan run.
brandDomainstringThe brand's own domain, normalized.
totalProbesnumberTotal engine probes in the scan run.
probesWithCitationsnumberHow many probes returned at least one cited source.
sourcesarrayCited domains ranked by count.
sources[].domainstringThe cited domain.
sources[].countnumberHow many probes cited this domain.
sources[].enginesstring[]Engine display names that cited the domain.
sources[].queryCountnumberHow many distinct queries surfaced the domain.
sources[].isOwnbooleanTrue when the domain is the brand's own domain.

Empty state (no stored scan yet)

{ "schema_version": "1.0", "hasAudit": false, "sources": [] }
GET/api/connector/reputation/:brandId

Returns the reputation signal detail from the latest scan: review platform coverage, citation footprint, mention accuracy, sentiment flags, and prioritized diagnoses.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0.

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
hasDatabooleanFalse when no stored scan or no reputation data exists for this brand and location.
scorenumberReputation signal score.
bandstringBand label for the reputation signal.
statusstringStatus label for the reputation signal.
reviewPlatformsFoundstring[]Review platforms where the brand was found.
aggregateRatingnumber | nullAggregate rating when one was detected. Null when none was found.
citationDomainsstring[]Third-party domains citing the brand.
accurateMentionsnumberScanned citations that mention the exact brand name in their title or description.
citationsScannednumberTotal citations scanned for accuracy.
negativeSnippetsnumberSearch snippets containing negative language.
serpAvailablebooleanWhether search result data was available for this measurement.
diagnosesarrayPrioritized findings, sorted by recoverable points. Each has id, title, points, finding, and action.

Empty state (no stored scan yet)

{ "schema_version": "1.0", "hasData": false }
GET/api/connector/publish-prescription/:brandId

Returns the publish prescription: the queries where the brand was not cited, grouped by gap type, so you know exactly what content to publish.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0.

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
hasDatabooleanFalse when no stored scan with probe data exists for this brand and location.
totalQueriesnumberTotal distinct queries measured in the scan.
coveredQueriesnumberQueries where every engine cited the brand.
gapQueriesnumberQueries with at least one engine gap.
prescriptionarrayGap queries sorted with total gaps first.
prescription[].querystringThe measured query.
prescription[].enginesCitednumberEngines that cited the brand for this query.
prescription[].enginesTotalnumberEngines that were probed for this query.
prescription[].gapTypestringEither "total_gap" (no engine cited the brand) or "partial_gap".
prescription[].uncitedEnginesstring[]Engine display names that did not cite the brand.
contentGapsarrayContent gaps sourced from real search query data when a search data connection exists. Empty otherwise.
contentGapSourcestringEither "real_search_queries" or "none". Content gaps are never fabricated.

Empty state (no stored scan yet)

{ "schema_version": "1.0", "hasData": false }
GET/api/connector/fix-file/:brandIdPro plan

Returns the fix file built from the latest scan: an AI-ready markdown document plus a machine-readable JSON document with stable item IDs.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0.
formatquerySet format=json to receive the schema-versioned JSON fix file document directly as the response body.

Response fields

hasAuditbooleanFalse when no stored scan exists for this brand and location.
filenamestringSuggested filename for the markdown document.
markdownstringThe full markdown fix file.
jsonFilenamestringSuggested filename for the JSON document.
jsonobjectThe machine-readable fix file document. Carries its own schema_version ("1.0").
compositenumber | nullComposite Signal Score of the run the file was built from.
bandstring | nullBand label for the composite score.
runCreatedAtstringTimestamp of the scan run.
generatedAtstringTimestamp when the fix file was generated.

Empty state (no stored scan yet)

{ "hasAudit": false }
Requires a Pro plan. With ?format=json the response body is the JSON fix file document itself, with schema_version "1.0" at its top level. Each item includes a stable id, a title, an executor label (CODE or MANUAL), a priority, evidence sourced from the engine responses, and a code block where one applies.
POST/api/connector/rescan/:brandIdPro plan

Triggers a fresh measurement for the brand. The AI engines are queried live and all scores, citations, and fix items are rebuilt from the new responses.

Parameters

brandIdpathBrand ID from /api/connector/brands.
locationIndexqueryZero-based location index. Defaults to 0.

Response fields

schema_versionstringSchema version of this response. Currently "1.0".
startedbooleanTrue when the scan ran. False responses include a reason field.
runIdnumber | nullID of the new scan run.
compositenumber | nullComposite Signal Score from the new run.
bandstring | nullBand label for the new composite score.
deltaobject | nullMeasured change since the previous run: compositeDelta and the previous composite. Null when no comparable previous run exists. The delta reports measured change only and never attributes causation.
Requires a Pro plan. Each call counts against the plan's monthly scan quota. When the quota is reached, the response is a 403 with started false, limitReached true, and the resetDate. Recommended flow: run a baseline scan, apply your fixes, then rescan to verify the measured change.
POST/mcp

Model Context Protocol endpoint for AI assistant integrations. Exposes the same data as structured tool calls, including get_fix_file and trigger_rescan plus the core signal data tools. Works with Claude, ChatGPT, and any assistant that supports the MCP standard. The same API key used for REST calls works here.

Error responses

400

Invalid request input, for example a brandId that is not a positive integer or a negative locationIndex.

401

Missing or invalid API key. Sent when no key is provided, or when the key or token is invalid, expired, or revoked.

403

The key belongs to an account without the required plan, the brand is not owned by the key holder, or the monthly scan quota is reached on rescan (the body then carries limitReached true and a resetDate).

500

Server error. The body carries a message field describing the failure.

The only usage limit in effect today is the monthly scan quota, which applies to POST /api/connector/rescan. Read endpoints do not consume scan quota.

Fix file JSON format

The ?format=json option returns a schema-versioned document. The schema_version field is stable and will be incremented if the document shape changes, so your integration can handle version transitions explicitly.

Response shape, schema_version 1.0
{
  "schema_version": "1.0",
  "brand": "example.com",
  "generated_at": "2026-07-16T06:00:00Z",
  "items": [
    {
      "id": "nap-consistency-001",         // stable across rescans
      "title": "Align NAP across all citation sources",
      "executor": "MANUAL",               // MANUAL | CODE
      "priority": "high",                 // high | medium | low
      "evidence": "Name mismatch on 3 of 6 engines",
      "code": null
    },
    {
      "id": "schema-org-localBusiness-001",
      "title": "Add LocalBusiness schema to homepage",
      "executor": "CODE",
      "priority": "high",
      "evidence": "No structured data detected in engine responses",
      "code": "<script type=\"application/ld+json\">...</script>"
    }
  ]
}

Machine-readable OpenAPI specification

The full connector API is described in an OpenAPI 3.1 spec served as plain JSON. Any crawler, AI agent, or integration tool can fetch it directly without running JavaScript.

GET /openapi.json

Covers all seven connector endpoints with request parameters, response schemas, empty states, both authentication forms, and error codes.

AI assistant integrations via MCP

The POST /mcp endpoint speaks the Model Context Protocol, so an AI assistant can call Signal Scanner as a tool directly inside a conversation. The same API key used for REST calls works here.

The MCP tools available today include get_fix_file and trigger_rescan, plus the core signal data tools. This works with assistants that support the MCP standard.

Ready to connect?

Signal Scanner is the independent AI-visibility layer other tools can build on. The data is real, stored, and traceable to engine responses. Talk to us and we will set up the integration with you.