Signal API
Site Audit as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Site Audit

Read current website health, pages, categories, and findings for a project or location. Audit execution is scheduled by Signal; the public API does not start audits manually.

ProjectLocation
GET
/projects/{project_id}/site_audit

Returns the current score state, page and finding totals, blocking details, and latest audit status.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response envelope

project_id:uuidsite_audit:SiteAuditOverview
project_iduuid

Resolved project identifier.

site_auditSiteAuditOverview

Current Site Audit state and totals.

Object

SiteAuditOverview

score_resultobject

Current, refreshing, or unavailable score state.

blocking_detailsobject | null

Public crawler-blocking diagnostics.

pagesobject

Inventory and latest audit-status counts.

findingsobject

Open finding counts by severity and category.

latest_stepobject | null

Latest scheduled Site Audit step and timing.

last_page_audited_atdatetime | null

Latest page audit completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

Score

overall_scorenumber

Overall score from 0 to 100.

technical_scorenumber

Technical pillar score when available.

content_scorenumber

Content pillar score when available.

category_scoresobject

Scores keyed by normalized category.

confidencenumber

Score confidence when available.

coveragenumber

Audited page coverage when available.

issue_countsobject

Finding counts represented by the score.

deltasobject

Changes from the previous score.

score_versionstring

Scoring implementation version.

check_versionstring

Site Audit check-set version.

scored_atdatetime

Time the score was calculated.

Object

BlockingAudit

statusstring

Blocking audit status.

pagespeed_statusstring | null

PageSpeed collection status.

error_codestring | null

Stable audit failure code.

completed_atdatetime | null

Audit completion time.

created_atdatetime

Audit creation time.

Object

BlockingDetails

providerstring

Detected blocking provider.

titlestring

Public blocking summary.

descriptionstring

Public explanation of the block.

recommendationstring

Recommended remediation.

http_statusinteger | null

Observed HTTP status.

diagnosticobject | null

Sanitized provider diagnostic.

allowlist_ipsstring[]

Signal crawler IPs to allow.

user_agentstring

Signal crawler user agent.

affected_urlURL | null

Sanitized blocked URL.

last_seen_atdatetime | null

Most recent blocking observation.

Object

OverviewPages

totalinteger

All known pages.

activeinteger

Pages in the active inventory.

removedinteger

Pages removed from the active inventory.

by_discovery_sourceobject

Active page counts keyed by discovery source.

latest_audit_statusesobject

Latest page-run counts keyed by status.

Object

FindingSummary

totalinteger

Total visible findings.

openinteger

Open visible findings.

by_statusobject

Counts keyed by finding status.

open_by_severityobject

Open counts keyed by severity.

open_by_categoryobject

Open counts keyed by normalized category.

Object

LatestStep

statusstring

Scheduled Site Audit step status.

started_atdatetime | null

Step start time.

completed_atdatetime | null

Step completion time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "site_audit": {
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 86.4,
        "technical_score": 90.2,
        "content_score": 83.3,
        "category_scores": {
          "performance": 78.0,
          "crawlability": 94.0,
          "security": 96.0,
          "structured_data": 82.0,
          "content_quality": 81.0,
          "content_structure": 88.0,
          "meta_onpage": 91.0,
          "aeo_readiness": 76.0
        },
        "confidence": 0.96,
        "coverage": 1.0,
        "issue_counts": {"critical": 0, "high": 2, "medium": 5},
        "deltas": {"overall_score": 2.1},
        "score_version": "v1",
        "check_version": "v1",
        "scored_at": "2026-08-09T09:30:00Z"
      }
    },
    "blocking_details": null,
    "pages": {
      "total": 42,
      "active": 42,
      "removed": 0,
      "by_discovery_source": {"sitemap": 42},
      "latest_audit_statuses": {"succeeded": 42}
    },
    "findings": {
      "total": 18,
      "open": 7,
      "by_status": {"open": 7, "resolved": 11},
      "open_by_severity": {"high": 2, "medium": 5},
      "open_by_category": {"meta_onpage": 3, "crawlability": 4}
    },
    "latest_step": {
      "status": "succeeded",
      "started_at": "2026-08-09T09:25:00Z",
      "completed_at": "2026-08-09T09:31:00Z"
    },
    "last_page_audited_at": "2026-08-09T09:30:45Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/site_audit/categories

Returns current category scores and the metrics shown in the Site Audit technical and content views.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response body

project_id:uuidstate:stringcurrent:booleanrefreshing:booleancategories:object | nullcategory_metrics:objectblocking_audit:object | nullscore_version:string | nullcheck_version:string | null
project_iduuid

Resolved project identifier.

statestring

Current score state.

currentboolean

Whether scores represent the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

categoriesobject | null

Score keyed by Site Audit category.

category_metricsobject

Metrics and sections keyed by category.

blocking_auditobject | null

Audit currently refreshing or blocking scoring.

score_versionstring | null

Scoring implementation version.

check_versionstring | null

Site Audit check-set version.

Object

CategoryMetrics

generated_atdatetime | null

Metric generation time.

total_pagesinteger

Pages represented by these metrics.

categoriesobject<string, CategoryMetric>

Metrics keyed by normalized Site Audit category.

Object

CategoryMetric

scorenumber | null

Category score.

issue_countinteger

Findings in this category.

affected_pagesinteger

Distinct affected pages.

severity_countsobject

Finding counts keyed by severity.

metricsMetric[]

Category-specific headline metrics.

sectionsobject[]

Category-specific detail sections.

Object

Metric

keystring

Stable metric key.

labelstring

Display label.

valuenumber | string | null

Metric value.

suffixstring | null

Optional display suffix.

tonestring | null

Optional display tone.

Object

BlockingAudit

statusstring

Blocking audit status.

pagespeed_statusstring | null

PageSpeed collection status.

error_codestring | null

Stable audit failure code.

completed_atdatetime | null

Audit completion time.

created_atdatetime

Audit creation time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/categories' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "state": "current",
  "current": true,
  "refreshing": false,
  "categories": {"crawlability": 94.0, "content_quality": 81.0},
  "category_metrics": {
    "generated_at": "2026-08-09T09:30:00Z",
    "total_pages": 42,
    "categories": {
      "crawlability": {
        "score": 94.0,
        "issue_count": 4,
        "affected_pages": 3,
        "severity_counts": {"medium": 4},
        "metrics": [],
        "sections": []
      }
    }
  },
  "score_version": "v1",
  "check_version": "v1",
  "blocking_audit": null
}
Example scopeCategory maps can contain every supported category; the example shows representative entries to keep it readable.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/site_audit/pages

Lists the current page inventory with score, latest run, and finding summaries.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Records per page. Maximum: 50.

OptionalDefault: 20
qstring

URL or path search. Maximum: 200 characters.

Optional
statusactive | removed

Inventory status filter.

OptionalDefault: active
discovery_sourceseed | sitemap | crawl | provider | manual

Discovery source filter.

Optional
audit_statuspending | running | succeeded | failed

Latest page audit status.

Optional
sortlast_audited_at | url | score | issues

Sort field.

OptionalDefault: last_audited_at
directionasc | desc

Sort direction.

OptionalDefault: desc
Response

Response envelope

project_id:uuidpages:Page[]pagination:Pagination
project_iduuid

Resolved project identifier.

pagesPage[]

Matching audited pages.

paginationPagination

Offset pagination metadata.

Object

Page

iduuid

Audited page identifier.

urlURL

Sanitized page URL.

normalized_urlURL

Canonical URL used to identify the page.

hoststring

Page hostname.

pathstring

Page path.

statusactive | removed

Inventory status.

discovery_sourceseed | sitemap | crawl | provider | manual

How Signal discovered the page.

first_discovered_atdatetime

Time Signal first discovered the page.

last_discovered_atdatetime

Most recent discovery time.

last_audited_atdatetime | null

Most recent completed audit time.

latest_runobject | null

Latest page audit status and public fetch details.

score_resultobject

Current page score state and score.

open_findingsobject

Open finding total and severity counts.

Object

LatestRun

statuspending | running | succeeded | failed

Page audit status.

http_statusinteger | null

Observed HTTP status.

final_urlURL | null

Sanitized final URL after redirects.

fetch_msinteger | null

Origin fetch duration in milliseconds.

error_codestring | null

Stable failure code.

error_messagestring | null

Safe public failure message.

completed_atdatetime | null

Completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

PageScore

overall_scorenumber

Page score from 0 to 100.

category_scoresobject

Page scores keyed by normalized category.

issue_countsobject

Page finding counts represented by the score.

Object

OpenFindings

totalinteger

Total open customer-visible findings.

by_severityobject

Open counts keyed by severity.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records returned per page.

totalinteger

Total matching records.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/pages?page=1&per_page=20' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "pages": [{
    "id": "eb67fc48-e109-42cc-bbeb-1b2b8042bd14",
    "url": "https://example.com/",
    "normalized_url": "https://example.com/",
    "host": "example.com",
    "path": "/",
    "status": "active",
    "discovery_source": "sitemap",
    "first_discovered_at": "2026-07-01T10:00:00Z",
    "last_discovered_at": "2026-08-09T09:20:00Z",
    "last_audited_at": "2026-08-09T09:30:00Z",
    "latest_run": {
      "status": "succeeded",
      "http_status": 200,
      "final_url": "https://example.com/",
      "fetch_ms": 218,
      "error_code": null,
      "error_message": null,
      "completed_at": "2026-08-09T09:30:00Z"
    },
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 92.0,
        "category_scores": {"crawlability": 96.0, "meta_onpage": 88.0},
        "issue_counts": {"medium": 1}
      }
    },
    "open_findings": {"total": 1, "by_severity": {"medium": 1}}
  }],
  "pagination": {"page": 1, "per_page": 20, "total": 42, "total_pages": 3}
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_filter

A filter value is not supported.

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.

GET

Get Site Audit page

/projects/{project_id}/site_audit/pages/{page_id}

Returns one page with its current score, latest audit, and open finding counts.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
page_iduuid

Site Audit page identifier.

Required
Response

Response envelope

project_id:uuidpage:Page
project_iduuid

Resolved project identifier.

pagePage

Requested audited page.

Object

Page

iduuid

Audited page identifier.

urlURL

Sanitized page URL.

normalized_urlURL

Canonical URL used to identify the page.

hoststring

Page hostname.

pathstring

Page path.

statusactive | removed

Inventory status.

discovery_sourceseed | sitemap | crawl | provider | manual

How Signal discovered the page.

first_discovered_atdatetime

Time Signal first discovered the page.

last_discovered_atdatetime

Most recent discovery time.

last_audited_atdatetime | null

Most recent completed audit time.

latest_runobject | null

Latest page audit status and public fetch details.

score_resultobject

Current page score state and score.

open_findingsobject

Open finding total and severity counts.

Object

LatestRun

statuspending | running | succeeded | failed

Page audit status.

http_statusinteger | null

Observed HTTP status.

final_urlURL | null

Sanitized final URL after redirects.

fetch_msinteger | null

Origin fetch duration in milliseconds.

error_codestring | null

Stable failure code.

error_messagestring | null

Safe public failure message.

completed_atdatetime | null

Completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

PageScore

overall_scorenumber

Page score from 0 to 100.

category_scoresobject

Page scores keyed by normalized category.

issue_countsobject

Page finding counts represented by the score.

Object

OpenFindings

totalinteger

Total open customer-visible findings.

by_severityobject

Open counts keyed by severity.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/pages/{page_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "page": {
    "id": "eb67fc48-e109-42cc-bbeb-1b2b8042bd14",
    "url": "https://example.com/",
    "normalized_url": "https://example.com/",
    "host": "example.com",
    "path": "/",
    "status": "active",
    "discovery_source": "sitemap",
    "first_discovered_at": "2026-07-01T10:00:00Z",
    "last_discovered_at": "2026-08-09T09:20:00Z",
    "last_audited_at": "2026-08-09T09:30:00Z",
    "latest_run": {
      "status": "succeeded",
      "http_status": 200,
      "final_url": "https://example.com/",
      "fetch_ms": 218,
      "error_code": null,
      "error_message": null,
      "completed_at": "2026-08-09T09:30:00Z"
    },
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 92.0,
        "category_scores": {"crawlability": 96.0, "meta_onpage": 88.0},
        "issue_counts": {"medium": 1}
      }
    },
    "open_findings": {"total": 1, "by_severity": {"medium": 1}}
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/site_audit/findings

Lists individual findings or groups open findings by check when grouped=true.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Records per page. Maximum: 50.

OptionalDefault: 20
groupedboolean

Return open findings grouped by check. Grouped responses are not paginated.

OptionalDefault: false
limitinteger

Grouped result limit from 1 to 20.

OptionalDefault: 20
qstring

Finding text search. Maximum: 200 characters.

Optional
statusopen | resolved | ignored | all

Status filter for individual findings.

OptionalDefault: open
severitycritical | high | medium | low | info

Severity filter.

Optional
categorySiteAuditCategory

performance, crawlability, security, structured_data, content_quality, content_structure, meta_onpage, or aeo_readiness.

Optional
areatechnical | content

Finding area filter.

Optional
page_iduuid

Return findings for one audited page.

Optional
Response

Individual response envelope

project_id:uuidgrouped:falsefindings:Finding[]summary:objectpagination:Pagination
project_iduuid

Resolved project identifier.

groupedfalse

Indicates an individual finding response.

findingsFinding[]

Paginated matching findings.

summaryobject

Scope-wide finding totals and status counts.

paginationPagination

Offset pagination metadata.

Response

Grouped response envelope

project_id:uuidgrouped:truetruncated:booleangroups:FindingGroup[]
project_iduuid

Resolved project identifier.

groupedtrue

Indicates a grouped response.

truncatedboolean

Whether the grouped result was bounded before all matches were represented.

groupsFindingGroup[]

Up to 20 groups, ordered by severity.

Object

Finding

iduuid

Finding identifier.

codestring

Stable Site Audit check code.

categorystring

Normalized technical or content category.

severitycritical | high | medium | low | info

Current severity.

statusopen | resolved | ignored

Current finding status.

target_kindstring

Type of resource affected by the finding.

targetstring | null

Affected page or target.

titlestring

Finding title.

descriptionstring | null

Observed condition.

recommendationstring | null

Recommended remediation.

occurrencesinteger

Number of times the finding has been observed.

first_seen_atdatetime

Time the finding was first observed.

last_seen_atdatetime

Most recent observation time.

resolved_atdatetime | null

Time the finding resolved.

Object

FindingGroup

codestring

Shared Site Audit check code.

titlestring

Representative title.

descriptionstring | null

Representative description.

recommendationstring | null

Representative recommendation.

severitycritical | high | medium | low | info

Highest severity in the group.

categorySiteAuditCategory

Normalized category.

pillartechnical | content

Top-level Site Audit area.

occurrencesinteger

Occurrences represented by the bounded result set.

affected_pagesinteger

Distinct affected pages represented by the result set.

findings_countinteger

Matching findings represented by the result set.

findings_truncatedboolean

Whether the findings array is incomplete.

findingsFinding[]

Up to 50 matching findings.

Object

FindingSummary

totalinteger

Total visible findings.

openinteger

Open visible findings.

by_statusobject

Counts keyed by finding status.

open_by_severityobject

Open counts keyed by severity.

open_by_categoryobject

Open counts keyed by normalized category.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records returned per page.

totalinteger

Total matching records.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/findings?grouped=true&severity=high' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "grouped": true,
  "truncated": false,
  "groups": [{
    "code": "missing_title",
    "title": "Missing title",
    "severity": "high",
    "category": "meta_onpage",
    "pillar": "content",
    "occurrences": 1,
    "affected_pages": 1,
    "findings_count": 1,
    "findings_truncated": false,
    "findings": [{
      "id": "3c77a8fa-d0ea-49f6-a49e-a6ae23e33ef3",
      "code": "missing_title",
      "category": "meta_onpage",
      "severity": "high",
      "status": "open",
      "target_kind": "page",
      "target": "https://example.com/about",
      "title": "Missing title",
      "description": "The page does not define a title.",
      "recommendation": "Add a concise, descriptive title.",
      "occurrences": 1,
      "first_seen_at": "2026-08-01T10:00:00Z",
      "last_seen_at": "2026-08-09T09:30:00Z",
      "resolved_at": null
    }]
  }]
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_filter

A filter value is not supported.

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/site_audit/findings/{finding_id}

Returns one finding and up to 100 recent observations.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
finding_iduuid

Site Audit finding identifier.

Required
Response

Response envelope

project_id:uuidfinding:FindingDetailobservations:Observation[]
project_iduuid

Resolved project identifier.

findingFindingDetail

Requested finding.

observationsObservation[]

Up to 100 observations, newest first.

Object

FindingDetail

iduuid

Finding identifier.

codestring

Stable Site Audit check code.

categorystring

Normalized technical or content category.

severitycritical | high | medium | low | info

Current severity.

statusopen | resolved | ignored

Current finding status.

target_kindstring

Type of resource affected by the finding.

targetstring | null

Affected page or target.

titlestring

Finding title.

descriptionstring | null

Observed condition.

recommendationstring | null

Recommended remediation.

occurrencesinteger

Number of times the finding has been observed.

first_seen_atdatetime

Time the finding was first observed.

last_seen_atdatetime

Most recent observation time.

resolved_atdatetime | null

Time the finding resolved.

evidenceobject

Sanitized evidence supporting the finding.

Object

Observation

outcomedetected | resolved

Finding state during this observation.

severitycritical | high | medium | low | info

Observed severity.

evidenceobject

Sanitized evidence captured during this observation.

observed_atdatetime

Observation time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/findings/{finding_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "finding": {
    "id": "3c77a8fa-d0ea-49f6-a49e-a6ae23e33ef3",
    "code": "missing_title",
    "category": "meta_onpage",
    "severity": "high",
    "status": "open",
    "target_kind": "page",
    "target": "https://example.com/about",
    "title": "Missing title",
    "description": "The page does not define a title.",
    "recommendation": "Add a concise, descriptive title.",
    "evidence": {},
    "occurrences": 2,
    "first_seen_at": "2026-08-01T10:00:00Z",
    "last_seen_at": "2026-08-09T09:30:00Z",
    "resolved_at": null
  },
  "observations": []
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/site_audit/settings

Returns sitemap and crawl-discovery settings.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response envelope

project_id:uuidsettings:SiteAuditSettings
project_iduuid

Resolved project identifier.

settingsSiteAuditSettings

Current discovery settings.

Object

SiteAuditSettings

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

crawl_include_patternsstring[]

Path patterns included during crawl discovery.

crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/settings' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "settings": {
    "sitemap_urls": ["https://example.com/sitemap.xml"],
    "crawl_include_patterns": ["/docs/*"],
    "crawl_exclude_patterns": ["/private/*"]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

PATCH
/projects/{project_id}/site_audit/settings

Updates sitemap and crawl patterns without starting an audit or inventory synchronization.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
PATCH semanticsOmitted fields remain unchanged. Send an empty array to clear a setting. Sitemap URLs are limited to 20; each crawl-pattern array is limited to 50 strings, with at most 500 characters per string.
Parameters

JSON body

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

Optional
crawl_include_patternsstring[]

Path patterns included during crawl discovery.

Optional
crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Optional
Response

Response envelope

project_id:uuidsettings:SiteAuditSettings
project_iduuid

Resolved project identifier.

settingsSiteAuditSettings

Updated discovery settings.

Object

SiteAuditSettings

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

crawl_include_patternsstring[]

Path patterns included during crawl discovery.

crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Request and response

Example requestcURL
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/settings' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"sitemap_urls":["https://example.com/sitemap.xml"],"crawl_exclude_patterns":["/private/*"]}'
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "settings": {
    "sitemap_urls": ["https://example.com/sitemap.xml"],
    "crawl_include_patterns": ["/docs/*"],
    "crawl_exclude_patterns": ["/private/*"]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable | superadmin_managed

The key lacks access, Site Audit is disabled, or writes are centrally managed.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.