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

Actions

Retrieve prioritized recommendations, supporting findings, implementation guides, status, and measured outcomes.

API scopeThese endpoints are available at both scopes.
Choose the resource whose data you want to manage.Learn about scopes →

Your selection updates every endpoint path, path parameter, and example on this page.

Actions are generated automatically from current findings and are owned by the selected project or location scope. They are available through the retrieval endpoints below. The resolved status is system-managed and cannot be selected through the API.
GET
project/projects/{project_id}/actions

Returns actions for the selected project, with server-side filtering and pagination.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

qstring

Search titles, descriptions, recommendations, and targets.

Optional
statusstring

active, todo, in_progress, completed, dismissed, or resolved. active includes todo and in_progress.

OptionalDefault: active
prioritystring

low, medium, high, or critical.

Optional
action_typestring

Restrict results to one action type.

Optional
effort_levellow | medium | high

Restrict results by estimated effort.

Optional
source_categorystring

Restrict results by work area.

Optional
topic_iduuid

Return actions linked to one topic.

Optional
pageinteger

The 1-based page number.

OptionalDefault: 1
per_pageinteger

Number of actions per page. Maximum: 100.

OptionalDefault: 25
Response

Response envelope

project_id:uuidactions:Action[]pagination:Pagination
project_iduuid

Resolved Ceyo project identifier.

actionsAction[]

Actions matching the selected filters.

paginationPagination

Pagination metadata.

Object

Action

iduuid

Unique action identifier.

statusstring

todo, in_progress, completed, dismissed, or resolved.

prioritystring

low, medium, high, or critical.

expected_outcomeobject

How the impact was estimated. `state` is critical_rule, modelled, directional, or unknown. `score` (0-100), `range`, and `unit` are only present when state is modelled; `assumption` explains why. Display "unknown" rather than a number for unknown and directional outcomes.

estimated_impactinteger

Deprecated: relative ranking score from 0 to 100, not a forecast. Show expected_outcome to customers; this value is present even when no outcome can be modelled.

effort_levellow | medium | high

Estimated implementation effort.

feasibilitylow | medium | high

Estimated ability to complete the recommendation.

source_categorystring

owned, earned, reputation, local, competitive, operational, or general.

content_formatstring | null

Recommended deliverable format when relevant.

action_typestring

technical, content, visibility, competitor, listing, earned_editorial, earned_ugc, earned_reference, sentiment_correction, general, access, measurement_fix, entity, facts_page, claim_parity, content_extend, local_template, reputation_programme, marketplace_listing, directory_listing, list_inclusion, partner_integration, community, or site_health.

titlestring

Short action title.

descriptionstring | null

Problem or opportunity addressed by the action.

recommendationstring | null

Recommended outcome or approach.

target_kindstring

Type of resource targeted by the action.

targetstring | null

Target URL, prompt reference, profile, or scope value.

structured_targetStructuredTarget | null

Execution-ready target label, platform, URL, and state.

dependenciesActionDependency[]

Actions that should be completed first.

external_profileExternalProfile | null

URL and availability status for an external profile.

diagnosisobject | null

Structured diagnosis behind the selected action when available.

expected_liftobject | null

Directional expected-lift estimate and assumptions when available.

validationValidation | null

Metrics, success conditions, timing, and comparison used to validate the action.

validation_resultValidationResult | null

Result after validation has observed the completed action.

evidence_summaryobject | null

Bounded response, citation, and source evidence for the action. Each top_sources row may include supports: up to 3 competitors that source backs in AI answers.

fixesFix[] | null

Machine-readable corrections when the action comes from AI answers stating a business fact wrong: the stated value, the correct value, its source, and the third-party pages found carrying the wrong value. Null for every other action.

guideGuide | null

Structured implementation guide when available.

topicsTopicReference[]

Topics connected through supporting prompts and findings.

started_atdatetime | null

When the action first entered in_progress.

completed_atdatetime | null

When the action was completed.

measured_outcomeMeasuredOutcome | null

Targeted-prompt presence before and after completion. Present only when status is completed. Pending until the next visibility run can be compared.

dismissed_atdatetime | null

When the action was dismissed.

resolved_atdatetime | null

When supporting findings were automatically resolved.

created_atdatetime

Action creation time.

updated_atdatetime

Last action update time.

Object

StructuredTarget

labelstring | null

Target display label.

platformstring | null

Target platform.

urlURL | null

Target URL.

stateexisting_page | proposed_page | external_destination | scope | null

How the target should be handled.

Object

ActionDependency

action_iduuid

Required action identifier.

titlestring

Required action title.

reasonstring | null

Why it should be completed first.

Object

ExternalProfile

statusfound | readable | unavailable | not_found | unknown

Availability of the external profile.

urlURL | null

External-profile URL.

Object

Validation

observation_window_daysinteger | null

Days allowed to observe the expected result.

comparisonstring | null

Plain-language description of how the result is evaluated.

Object

ValidationResult

statussuccess | failure | inconclusive | not_observable

Outcome of the latest validation observation.

reasonstring | null

Explanation when validation did not succeed.

observed_atdatetime | null

When the result was last observed.

window_ends_atdatetime | null

When the observation window ends.

Object

MeasuredOutcome

statusstring

pending or measured.

reasonstring | null

Present when pending: awaiting_post_completion_run, no_baseline_run, no_targeted_prompts, or missing_targeted_executions.

outcomestring | null

Present when measured: improved, unchanged, or declined.

targetedobject | null

Presence on this action’s validation prompts: before, after, and sample_size.

otherobject | null

Presence on all other prompts in the same runs: before, after, and sample_size.

baseline_atdatetime | null

When the pre-completion visibility run finished.

comparison_atdatetime | null

When the post-completion visibility run finished.

Object

Fix

fieldphone | website | address | hours | closed

The business fact AI answers get wrong.

qualifierstring | null

Weekday or weekday range for hours (monday … sunday, monday-saturday). Null for other fields.

wrongstring

The value AI answers state, normalized: HH:MM-HH:MM or closed for hours; E.164 for phone; permanently, temporarily, or moved for closed.

correctstring | null

The value on record, normalized the same way.

correct_sourcewebsite | location_record | google_business_profile | customer | null

Where the correct value comes from.

stated_bystring[]

AI models whose answers state the wrong value.

carried_byFixSource[]

Third-party pages the answers cite that were read and found stating the wrong value: domain, url, and a verbatim quote from the page. Empty when none was found; the fact then needs correcting on the business’s own surfaces.

Object

Guide

diagnosisstring

Concise explanation of the diagnosed issue.

gap_analysisstring

Difference between the current and desired state.

action_stepsstring[]

Ordered implementation steps.

validation_stepsstring[]

Checks used to confirm completion.

rollback_notesstring | null

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger | null

Estimated days before an outcome may become measurable.

success_metricsSuccessMetric[] | null

How success is measured for this action. Null when no measurable metric applies.

execution_artifactExecutionArtifact | null

Ready-to-use copy the action steps refer to: page text, brief, message or checklist.

Object

SuccessMetric

metricstring

What is measured.

baselinestring

Value before the action: plain words, or mentions over sampled AI answers such as "1/2".

target_directionincrease | decrease | maintain | reach

Expected direction of the metric.

evaluation_window_daysinteger

Days after completion before the metric is evaluated.

verification_methodstring

How the result is checked.

Object

ExecutionArtifact

typecontent_brief | outreach_template | implementation_checklist | schema_snippet

Kind of copy.

titlestring

Short title of the copy.

contentstring

The copy as plain text or Markdown. Bracketed placeholders such as [opening hours] are for the business to fill in.

languagestring | null

ISO 639-1 code when the copy is in a different language from the guide.

email{ to?: string, subject?: string, body: string } | null

outreach_template only: the pitch as an email. to is an address or a role such as "the editor". content holds the email body.

sections{ heading: string, content: string }[] | null

content_brief only: the page copy in parts (title tag, intro, FAQ…), each ready to paste. heading may be empty for an untitled intro. content holds the same copy as text.

fields{ name: string, value: string }[] | null

Listing actions: the profile fields to set (description, category, hours…) and the value for each. content holds the same fields as text.

Object

TopicReference

iduuid

Topic identifier.

namestring

Topic display name.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Number of records requested per page.

totalinteger

Total records matching the request.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions?status=active&priority=high&page=1' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "actions": [
    {
      "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
      "status": "in_progress",
      "priority": "high",
      "estimated_impact": 78,
      "expected_outcome": {
        "state": "modelled",
        "score": 78,
        "range": { "low": 31.0, "high": 77.5 },
        "unit": "percentage_points",
        "assumption": "Estimate based on current absence, lever fit, and feasibility."
      },
      "effort_level": "medium",
      "feasibility": "high",
      "source_category": "owned",
      "content_format": "comparison_page",
      "action_type": "content",
      "title": "Create a focused comparison page",
      "description": "Competitors are cited for high-intent comparison prompts.",
      "recommendation": "Publish a factual comparison addressing the observed gaps.",
      "target_kind": "site",
      "target": "https://example.com",
      "fixes": null,
      "topics": [
        {
          "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
          "name": "AI visibility platforms"
        }
      ],
      "started_at": "2026-07-30T10:05:00Z",
      "completed_at": null,
      "measured_outcome": null,
      "dismissed_at": null,
      "resolved_at": null,
      "created_at": "2026-07-20T08:30:00Z",
      "updated_at": "2026-07-30T10:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}
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": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

Project, location, or action was not found.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/actions/{action_id}

Returns one action, its structured implementation guide, and all supporting findings in the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
action_iduuid

Action identifier.

Required
Response

Action response envelope

project_id:uuidaction:Actionfindings:Finding[]
project_iduuid

Resolved Ceyo project identifier.

actionAction

Requested action and its implementation guide.

findingsFinding[]

Supporting findings linked to the action.

Object

Action

iduuid

Unique action identifier.

statusstring

todo, in_progress, completed, dismissed, or resolved.

prioritystring

low, medium, high, or critical.

expected_outcomeobject

How the impact was estimated. `state` is critical_rule, modelled, directional, or unknown. `score` (0-100), `range`, and `unit` are only present when state is modelled; `assumption` explains why. Display "unknown" rather than a number for unknown and directional outcomes.

estimated_impactinteger

Deprecated: relative ranking score from 0 to 100, not a forecast. Show expected_outcome to customers; this value is present even when no outcome can be modelled.

effort_levellow | medium | high

Estimated implementation effort.

feasibilitylow | medium | high

Estimated ability to complete the recommendation.

source_categorystring

owned, earned, reputation, local, competitive, operational, or general.

content_formatstring | null

Recommended deliverable format when relevant.

action_typestring

technical, content, visibility, competitor, listing, earned_editorial, earned_ugc, earned_reference, sentiment_correction, general, access, measurement_fix, entity, facts_page, claim_parity, content_extend, local_template, reputation_programme, marketplace_listing, directory_listing, list_inclusion, partner_integration, community, or site_health.

titlestring

Short action title.

descriptionstring | null

Problem or opportunity addressed by the action.

recommendationstring | null

Recommended outcome or approach.

target_kindstring

Type of resource targeted by the action.

targetstring | null

Target URL, prompt reference, profile, or scope value.

structured_targetStructuredTarget | null

Execution-ready target label, platform, URL, and state.

dependenciesActionDependency[]

Actions that should be completed first.

external_profileExternalProfile | null

URL and availability status for an external profile.

diagnosisobject | null

Structured diagnosis behind the selected action when available.

expected_liftobject | null

Directional expected-lift estimate and assumptions when available.

validationValidation | null

Metrics, success conditions, timing, and comparison used to validate the action.

validation_resultValidationResult | null

Result after validation has observed the completed action.

evidence_summaryobject | null

Bounded response, citation, and source evidence for the action. Each top_sources row may include supports: up to 3 competitors that source backs in AI answers.

fixesFix[] | null

Machine-readable corrections when the action comes from AI answers stating a business fact wrong: the stated value, the correct value, its source, and the third-party pages found carrying the wrong value. Null for every other action.

guideGuide | null

Structured implementation guide when available.

topicsTopicReference[]

Topics connected through supporting prompts and findings.

started_atdatetime | null

When the action first entered in_progress.

completed_atdatetime | null

When the action was completed.

measured_outcomeMeasuredOutcome | null

Targeted-prompt presence before and after completion. Present only when status is completed. Pending until the next visibility run can be compared.

dismissed_atdatetime | null

When the action was dismissed.

resolved_atdatetime | null

When supporting findings were automatically resolved.

created_atdatetime

Action creation time.

updated_atdatetime

Last action update time.

Object

StructuredTarget

labelstring | null

Target display label.

platformstring | null

Target platform.

urlURL | null

Target URL.

stateexisting_page | proposed_page | external_destination | scope | null

How the target should be handled.

Object

ActionDependency

action_iduuid

Required action identifier.

titlestring

Required action title.

reasonstring | null

Why it should be completed first.

Object

ExternalProfile

statusfound | readable | unavailable | not_found | unknown

Availability of the external profile.

urlURL | null

External-profile URL.

Object

Validation

observation_window_daysinteger | null

Days allowed to observe the expected result.

comparisonstring | null

Plain-language description of how the result is evaluated.

Object

ValidationResult

statussuccess | failure | inconclusive | not_observable

Outcome of the latest validation observation.

reasonstring | null

Explanation when validation did not succeed.

observed_atdatetime | null

When the result was last observed.

window_ends_atdatetime | null

When the observation window ends.

Object

MeasuredOutcome

statusstring

pending or measured.

reasonstring | null

Present when pending: awaiting_post_completion_run, no_baseline_run, no_targeted_prompts, or missing_targeted_executions.

outcomestring | null

Present when measured: improved, unchanged, or declined.

targetedobject | null

Presence on this action’s validation prompts: before, after, and sample_size.

otherobject | null

Presence on all other prompts in the same runs: before, after, and sample_size.

baseline_atdatetime | null

When the pre-completion visibility run finished.

comparison_atdatetime | null

When the post-completion visibility run finished.

Object

Fix

fieldphone | website | address | hours | closed

The business fact AI answers get wrong.

qualifierstring | null

Weekday or weekday range for hours (monday … sunday, monday-saturday). Null for other fields.

wrongstring

The value AI answers state, normalized: HH:MM-HH:MM or closed for hours; E.164 for phone; permanently, temporarily, or moved for closed.

correctstring | null

The value on record, normalized the same way.

correct_sourcewebsite | location_record | google_business_profile | customer | null

Where the correct value comes from.

stated_bystring[]

AI models whose answers state the wrong value.

carried_byFixSource[]

Third-party pages the answers cite that were read and found stating the wrong value: domain, url, and a verbatim quote from the page. Empty when none was found; the fact then needs correcting on the business’s own surfaces.

Object

Guide

diagnosisstring

Concise explanation of the diagnosed issue.

gap_analysisstring

Difference between the current and desired state.

action_stepsstring[]

Ordered implementation steps.

validation_stepsstring[]

Checks used to confirm completion.

rollback_notesstring | null

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger | null

Estimated days before an outcome may become measurable.

success_metricsSuccessMetric[] | null

How success is measured for this action. Null when no measurable metric applies.

execution_artifactExecutionArtifact | null

Ready-to-use copy the action steps refer to: page text, brief, message or checklist.

Object

SuccessMetric

metricstring

What is measured.

baselinestring

Value before the action: plain words, or mentions over sampled AI answers such as "1/2".

target_directionincrease | decrease | maintain | reach

Expected direction of the metric.

evaluation_window_daysinteger

Days after completion before the metric is evaluated.

verification_methodstring

How the result is checked.

Object

ExecutionArtifact

typecontent_brief | outreach_template | implementation_checklist | schema_snippet

Kind of copy.

titlestring

Short title of the copy.

contentstring

The copy as plain text or Markdown. Bracketed placeholders such as [opening hours] are for the business to fill in.

languagestring | null

ISO 639-1 code when the copy is in a different language from the guide.

email{ to?: string, subject?: string, body: string } | null

outreach_template only: the pitch as an email. to is an address or a role such as "the editor". content holds the email body.

sections{ heading: string, content: string }[] | null

content_brief only: the page copy in parts (title tag, intro, FAQ…), each ready to paste. heading may be empty for an untitled intro. content holds the same copy as text.

fields{ name: string, value: string }[] | null

Listing actions: the profile fields to set (description, category, hours…) and the value for each. content holds the same fields as text.

Object

TopicReference

iduuid

Topic identifier.

namestring

Topic display name.

Object

Finding

sourcestring

Analysis source that produced the finding.

categorystring

Finding category.

severitystring

Finding severity.

statusstring

Current finding lifecycle status.

target_kindstring

Type of resource that produced the signal.

targetstring | null

Target value when available.

titlestring

Finding title.

descriptionstring | null

Evidence-backed finding description.

recommendationstring | null

Recommended response to the finding.

first_seen_atdatetime

First detection time.

last_seen_atdatetime

Most recent detection time.

resolved_atdatetime | null

Resolution time, when resolved.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "action": {
    "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
    "status": "in_progress",
    "priority": "high",
    "estimated_impact": 64,
    "effort_level": "low",
    "feasibility": "high",
    "source_category": "general",
    "content_format": null,
    "action_type": "directory_listing",
    "title": "Correct the Sunday opening hours on CityList",
    "description": "ChatGPT and Gemini tell customers the branch opens 09:00-19:00 on Sundays; the Google Business Profile states 10:00-18:00. The CityList page both assistants cite carries the wrong hours.",
    "recommendation": "Update the CityList listing to 10:00-18:00 on Sundays and confirm the hours match the Google Business Profile.",
    "target_kind": "domain",
    "target": "https://citylist.example/acme-phoenix",
    "structured_target": {
      "label": "CityList",
      "platform": "citylist.example",
      "url": "https://citylist.example/acme-phoenix",
      "state": "external_destination"
    },
    "external_profile": {
      "status": "readable",
      "url": "https://citylist.example/acme-phoenix"
    },
    "guide": {
      "diagnosis": "ChatGPT and Gemini cite the CityList page for Sunday hours, and it still lists 09:00-19:00.",
      "gap_analysis": "The Google Business Profile states 10:00-18:00 on Sundays; CityList is the only cited source with different hours.",
      "action_steps": [
        "Sign in to the CityList business dashboard for the Phoenix branch.",
        "Set the Sunday hours to 10:00-18:00 and save.",
        "Check that the public listing page shows the new hours."
      ],
      "validation_steps": [
        "Open https://citylist.example/acme-phoenix and confirm Sunday shows 10:00-18:00."
      ],
      "rollback_notes": null,
      "impact_prediction": "AI answers that cite CityList state the correct Sunday hours.",
      "impact_timeline_days": 21,
      "success_metrics": [
        {
          "metric": "AI answers stating the correct Sunday hours",
          "baseline": "ChatGPT 09:00-19:00, Gemini 09:00-19:00",
          "target_direction": "reach",
          "evaluation_window_days": 21,
          "verification_method": "Re-run the tracked prompts and compare the stated hours with the Google Business Profile."
        }
      ],
      "execution_artifact": {
        "type": "implementation_checklist",
        "title": "CityList hours update",
        "content": "Sunday: 10:00-18:00",
        "language": null,
        "email": null,
        "sections": null,
        "fields": [
          { "name": "Sunday hours", "value": "10:00-18:00" }
        ]
      }
    },
    "fixes": [
      {
        "field": "hours",
        "qualifier": "sunday",
        "wrong": "09:00-19:00",
        "correct": "10:00-18:00",
        "correct_source": "google_business_profile",
        "stated_by": ["chatgpt", "gemini"],
        "carried_by": [
          {
            "domain": "citylist.example",
            "url": "https://citylist.example/acme-phoenix",
            "quote": "Sunday 9:00 - 19:00"
          }
        ]
      }
    ],
    "topics": [],
    "started_at": "2026-07-30T10:05:00Z",
    "completed_at": null,
    "measured_outcome": null,
    "dismissed_at": null,
    "resolved_at": null,
    "created_at": "2026-07-20T08:30:00Z",
    "updated_at": "2026-07-30T10:05:00Z"
  },
  "findings": [
    {
      "source": "signals",
      "category": "fact_drift",
      "severity": "medium",
      "status": "open",
      "target_kind": "page",
      "target": "https://example.com/phoenix",
      "title": "AI answers state different opening hours",
      "description": "chatgpt and gemini give 09:00-19:00 for Sunday; the Google Business Profile states 10:00-18:00.",
      "recommendation": "Publish the correct Sunday hours (10:00-18:00) consistently on the website, the Google Business Profile and the listings AI assistants read, and correct the sources that carry 09:00-19:00.",
      "first_seen_at": "2026-07-10T07:30:00Z",
      "last_seen_at": "2026-07-30T09: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": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

Project, location, or action was not found.

429rate_limit_exceeded

Too many requests were made.

PATCH
project/projects/{project_id}/actions/{action_id}

Updates the customer-managed lifecycle status of an action. Resolved actions are controlled automatically by their supporting findings.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
action_iduuid

Action identifier.

Required
Request

Request body

statustodo | in_progress | completed | dismissed

New customer-managed action status.

Object

Allowed transitions

todo→ in_progress, completed, dismissed

A new action can be started, completed, or dismissed.

in_progress→ todo, completed, dismissed

Work can be paused, completed, or dismissed.

completed→ todo

A completed action can be reopened.

dismissed→ todo

A dismissed action can be reopened.

Response

Action response envelope

project_id:uuidaction:Action
project_iduuid

Resolved Ceyo project identifier.

actionAction

Updated action.

Object

Action

iduuid

Unique action identifier.

statusstring

todo, in_progress, completed, dismissed, or resolved.

prioritystring

low, medium, high, or critical.

expected_outcomeobject

How the impact was estimated. `state` is critical_rule, modelled, directional, or unknown. `score` (0-100), `range`, and `unit` are only present when state is modelled; `assumption` explains why. Display "unknown" rather than a number for unknown and directional outcomes.

estimated_impactinteger

Deprecated: relative ranking score from 0 to 100, not a forecast. Show expected_outcome to customers; this value is present even when no outcome can be modelled.

effort_levellow | medium | high

Estimated implementation effort.

feasibilitylow | medium | high

Estimated ability to complete the recommendation.

source_categorystring

owned, earned, reputation, local, competitive, operational, or general.

content_formatstring | null

Recommended deliverable format when relevant.

action_typestring

technical, content, visibility, competitor, listing, earned_editorial, earned_ugc, earned_reference, sentiment_correction, general, access, measurement_fix, entity, facts_page, claim_parity, content_extend, local_template, reputation_programme, marketplace_listing, directory_listing, list_inclusion, partner_integration, community, or site_health.

titlestring

Short action title.

descriptionstring | null

Problem or opportunity addressed by the action.

recommendationstring | null

Recommended outcome or approach.

target_kindstring

Type of resource targeted by the action.

targetstring | null

Target URL, prompt reference, profile, or scope value.

structured_targetStructuredTarget | null

Execution-ready target label, platform, URL, and state.

dependenciesActionDependency[]

Actions that should be completed first.

external_profileExternalProfile | null

URL and availability status for an external profile.

diagnosisobject | null

Structured diagnosis behind the selected action when available.

expected_liftobject | null

Directional expected-lift estimate and assumptions when available.

validationValidation | null

Metrics, success conditions, timing, and comparison used to validate the action.

validation_resultValidationResult | null

Result after validation has observed the completed action.

evidence_summaryobject | null

Bounded response, citation, and source evidence for the action. Each top_sources row may include supports: up to 3 competitors that source backs in AI answers.

fixesFix[] | null

Machine-readable corrections when the action comes from AI answers stating a business fact wrong: the stated value, the correct value, its source, and the third-party pages found carrying the wrong value. Null for every other action.

guideGuide | null

Structured implementation guide when available.

topicsTopicReference[]

Topics connected through supporting prompts and findings.

started_atdatetime | null

When the action first entered in_progress.

completed_atdatetime | null

When the action was completed.

measured_outcomeMeasuredOutcome | null

Targeted-prompt presence before and after completion. Present only when status is completed. Pending until the next visibility run can be compared.

dismissed_atdatetime | null

When the action was dismissed.

resolved_atdatetime | null

When supporting findings were automatically resolved.

created_atdatetime

Action creation time.

updated_atdatetime

Last action update time.

Object

StructuredTarget

labelstring | null

Target display label.

platformstring | null

Target platform.

urlURL | null

Target URL.

stateexisting_page | proposed_page | external_destination | scope | null

How the target should be handled.

Object

ActionDependency

action_iduuid

Required action identifier.

titlestring

Required action title.

reasonstring | null

Why it should be completed first.

Object

ExternalProfile

statusfound | readable | unavailable | not_found | unknown

Availability of the external profile.

urlURL | null

External-profile URL.

Object

Validation

observation_window_daysinteger | null

Days allowed to observe the expected result.

comparisonstring | null

Plain-language description of how the result is evaluated.

Object

ValidationResult

statussuccess | failure | inconclusive | not_observable

Outcome of the latest validation observation.

reasonstring | null

Explanation when validation did not succeed.

observed_atdatetime | null

When the result was last observed.

window_ends_atdatetime | null

When the observation window ends.

Object

MeasuredOutcome

statusstring

pending or measured.

reasonstring | null

Present when pending: awaiting_post_completion_run, no_baseline_run, no_targeted_prompts, or missing_targeted_executions.

outcomestring | null

Present when measured: improved, unchanged, or declined.

targetedobject | null

Presence on this action’s validation prompts: before, after, and sample_size.

otherobject | null

Presence on all other prompts in the same runs: before, after, and sample_size.

baseline_atdatetime | null

When the pre-completion visibility run finished.

comparison_atdatetime | null

When the post-completion visibility run finished.

Object

Fix

fieldphone | website | address | hours | closed

The business fact AI answers get wrong.

qualifierstring | null

Weekday or weekday range for hours (monday … sunday, monday-saturday). Null for other fields.

wrongstring

The value AI answers state, normalized: HH:MM-HH:MM or closed for hours; E.164 for phone; permanently, temporarily, or moved for closed.

correctstring | null

The value on record, normalized the same way.

correct_sourcewebsite | location_record | google_business_profile | customer | null

Where the correct value comes from.

stated_bystring[]

AI models whose answers state the wrong value.

carried_byFixSource[]

Third-party pages the answers cite that were read and found stating the wrong value: domain, url, and a verbatim quote from the page. Empty when none was found; the fact then needs correcting on the business’s own surfaces.

Object

Guide

diagnosisstring

Concise explanation of the diagnosed issue.

gap_analysisstring

Difference between the current and desired state.

action_stepsstring[]

Ordered implementation steps.

validation_stepsstring[]

Checks used to confirm completion.

rollback_notesstring | null

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger | null

Estimated days before an outcome may become measurable.

success_metricsSuccessMetric[] | null

How success is measured for this action. Null when no measurable metric applies.

execution_artifactExecutionArtifact | null

Ready-to-use copy the action steps refer to: page text, brief, message or checklist.

Object

SuccessMetric

metricstring

What is measured.

baselinestring

Value before the action: plain words, or mentions over sampled AI answers such as "1/2".

target_directionincrease | decrease | maintain | reach

Expected direction of the metric.

evaluation_window_daysinteger

Days after completion before the metric is evaluated.

verification_methodstring

How the result is checked.

Object

ExecutionArtifact

typecontent_brief | outreach_template | implementation_checklist | schema_snippet

Kind of copy.

titlestring

Short title of the copy.

contentstring

The copy as plain text or Markdown. Bracketed placeholders such as [opening hours] are for the business to fill in.

languagestring | null

ISO 639-1 code when the copy is in a different language from the guide.

email{ to?: string, subject?: string, body: string } | null

outreach_template only: the pitch as an email. to is an address or a role such as "the editor". content holds the email body.

sections{ heading: string, content: string }[] | null

content_brief only: the page copy in parts (title tag, intro, FAQ…), each ready to paste. heading may be empty for an untitled intro. content holds the same copy as text.

fields{ name: string, value: string }[] | null

Listing actions: the profile fields to set (description, category, hours…) and the value for each. content holds the same fields as text.

Object

TopicReference

iduuid

Topic identifier.

namestring

Topic display name.

Request and response

Example requestcURL
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{"status":"completed"}'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "action": {
    "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
    "status": "completed",
    "completed_at": "2026-07-31T10:15:00Z",
    "measured_outcome": {
      "status": "pending",
      "reason": "awaiting_post_completion_run"
    },
    "updated_at": "2026-07-31T10:15:00Z"
  }
}
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": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

Project, location, or action was not found.

409invalid_transition

The requested status transition is not allowed.

422invalid_status

The submitted status is not writable.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/actions/impact

Compares visibility signals before and after completed actions in the selected project. Actions remain pending until both baseline and comparison runs are available.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

start_ondate

First completion date to include.

OptionalDefault: 90 days before end_on
end_ondate

Last completion date to include.

OptionalDefault: Today
topic_iduuid

Measure actions connected to one topic.

Optional
action_typestring

Measure one action type.

Optional
Response

Response envelope

project_id:uuidperiod:ImpactPeriodsummary:ImpactSummarytimeline:ImpactTimelinePoint[]actions:ActionMeasurement[]
project_iduuid

Resolved Ceyo project identifier.

periodImpactPeriod

Resolved start_on and end_on.

summaryImpactSummary

Completed, measured, pending, and outcome totals.

timelineImpactTimelinePoint[]

Weekly completion and visibility outcome series.

actionsActionMeasurement[]

Measurements for up to 100 completed actions.

Object

ImpactPeriod

start_ondate

First completion date included in the measurement window.

end_ondate

Last completion date included in the measurement window.

Object

ImpactSummary

completed_actionsinteger

Completed actions included in the measurement window.

measured_actionsinteger

Actions with both baseline and comparison signals.

pending_actionsinteger

Actions awaiting an eligible baseline or comparison signal.

improvedinteger

Measured actions classified as improved.

unchangedinteger

Measured actions classified as unchanged.

declinedinteger

Measured actions classified as declined.

average_visibility_deltanumber | null

Mean visibility percentage-point change, or null when no action is measured.

average_citation_deltanumber | null

Mean citation-count change, or null when no action is measured.

average_sentiment_deltanumber | null

Mean sentiment-score change, or null when no comparable values exist.

Object

ImpactTimelinePoint

datedate

Start date of the represented week.

completedinteger

Actions completed during the represented week.

measuredinteger

Completed actions with an available measurement.

average_visibility_deltanumber | null

Mean visibility percentage-point change, or null when the week has no measurements.

Object

ActionMeasurement

iduuid

Action identifier.

titlestring

Action title.

action_typestring

Action type.

completed_atdatetime

Action completion time.

topicsTopicReference[]

Topics used to scope the measurement.

statusmeasured | pending

Measurement availability.

reasonno_baseline_run | awaiting_post_completion_run | null

Why a pending action cannot yet be measured.

outcomeimproved | unchanged | declined | null

Outcome derived from visibility change when measured.

baseline_atdatetime | null

Baseline run completion time.

comparison_atdatetime | null

Comparison run completion time.

baselineImpactSnapshot | null

Signals immediately before completion when measured.

comparisonImpactSnapshot | null

Latest eligible signals after completion when measured.

deltaActionMeasurementDelta | null

Signal changes when the action is measured.

Object

ActionMeasurementDelta

visibility_percentage_pointsnumber | null

Comparison visibility minus baseline visibility.

citation_countinteger | null

Comparison citation count minus baseline citation count.

sentiment_scorenumber | null

Comparison sentiment score minus baseline sentiment score.

average_positionnumber | null

Improvement in average position; positive values indicate movement toward position one.

Object

ImpactSnapshot

visibility_percentagenumber

Primary brand visibility percentage.

citation_countinteger

Distinct cited pages.

sentiment_scorenumber | null

Average primary-brand sentiment score.

average_positionnumber | null

Average primary-brand position.

Object

TopicReference

iduuid

Topic identifier.

namestring

Topic display name.

Outcome interpretationMeasurements show correlated before-and-after signals. They do not establish that an action was the only cause of a change.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/impact?start_on=2026-05-01&end_on=2026-07-30' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "period": {
    "start_on": "2026-05-01",
    "end_on": "2026-07-30"
  },
  "summary": {
    "completed_actions": 12,
    "measured_actions": 9,
    "pending_actions": 3,
    "improved": 6,
    "unchanged": 2,
    "declined": 1,
    "average_visibility_delta": 4.8,
    "average_citation_delta": 3.2,
    "average_sentiment_delta": 0.4
  },
  "timeline": [
    {
      "date": "2026-07-27",
      "completed": 3,
      "measured": 2,
      "average_visibility_delta": 5.1
    }
  ],
  "actions": [
    {
      "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
      "title": "Create a focused comparison page",
      "action_type": "content",
      "completed_at": "2026-07-10T10:15:00Z",
      "topics": [],
      "status": "measured",
      "outcome": "improved",
      "baseline_at": "2026-07-09T07:30:00Z",
      "comparison_at": "2026-07-30T09:30:00Z",
      "baseline": {
        "visibility_percentage": 35.0,
        "citation_count": 8,
        "sentiment_score": 6.8,
        "average_position": 3.4
      },
      "comparison": {
        "visibility_percentage": 42.5,
        "citation_count": 13,
        "sentiment_score": 7.3,
        "average_position": 2.8
      },
      "delta": {
        "visibility_percentage_points": 7.5,
        "citation_count": 5,
        "sentiment_score": 0.5,
        "average_position": 0.6
      }
    }
  ]
}
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": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

Project, location, or action was not found.

429rate_limit_exceeded

Too many requests were made.