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.

ProjectLocation
Actions are generated automatically from current findings and are available through the retrieval endpoints below. The resolved status is system-managed and cannot be selected through the API.
GET
/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.

estimated_impactinteger

Relative expected impact from 0 to 100.

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, or general.

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.

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.

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

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

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger

Estimated days before an outcome may become measurable.

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,
      "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",
      "topics": [
        {
          "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
          "name": "AI visibility platforms"
        }
      ],
      "started_at": "2026-07-30T10:05:00Z",
      "completed_at": 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
/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.

estimated_impactinteger

Relative expected impact from 0 to 100.

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, or general.

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.

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.

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

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

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger

Estimated days before an outcome may become measurable.

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": 78,
    "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",
    "guide": {
      "diagnosis": "Competitors own the strongest comparison citations.",
      "gap_analysis": "The site does not answer the comparison intent directly.",
      "action_steps": [
        "Collect product evidence for each comparison criterion.",
        "Publish a transparent comparison page."
      ],
      "validation_steps": [
        "Confirm every claim has a source.",
        "Request indexing after publication."
      ],
      "rollback_notes": "Remove unsupported claims if evidence changes.",
      "impact_prediction": "Improved relevance for comparison prompts.",
      "impact_timeline_days": 30
    },
    "topics": [],
    "started_at": "2026-07-30T10:05:00Z",
    "completed_at": null,
    "dismissed_at": null,
    "resolved_at": null,
    "created_at": "2026-07-20T08:30:00Z",
    "updated_at": "2026-07-30T10:05:00Z"
  },
  "findings": [
    {
      "source": "visibility",
      "category": "citation_gap",
      "severity": "high",
      "status": "open",
      "target_kind": "site",
      "target": "example.com",
      "title": "Competitors own comparison citations",
      "description": "Competitor pages are repeatedly cited.",
      "recommendation": "Address the observed comparison intent.",
      "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
/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.

estimated_impactinteger

Relative expected impact from 0 to 100.

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, or general.

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.

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.

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

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

Recovery guidance when a change must be reverted.

impact_predictionstring

Expected outcome after implementation.

impact_timeline_daysinteger

Estimated days before an outcome may become measurable.

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",
    "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
/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.