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

Suggested prompts

Review, track, or dismiss prompt suggestions generated from visibility evidence.

ProjectLocation
GET
/projects/{project_id}/visibility/suggested_prompts

Returns paginated diagnosis- and fanout-sourced prompt suggestions for the selected project. Suggestions are separate from tracked prompts and consume no capacity.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

qstring

Search suggestion content, reason, and topic name.

Optional
statussuggested | tracked | dismissed | expired

Suggestion lifecycle state to return.

OptionalDefault: suggested
pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Suggestions per page. Maximum: 100.

OptionalDefault: 20
Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]pagination:Pagination
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions matching the selected status and search.

paginationPagination

Suggestion pagination metadata.

Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records requested per page.

totalinteger

Total records matching the filters.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts?status=suggested&page=1&per_page=20' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "suggested",
      "tracked_prompt_id": null,
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": null,
      "dismissed_at": null,
      "expired_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5,
    "total_pages": 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

400invalid_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.

POST
/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/track

Converts one visible suggestion into an active prompt and schedules a visibility run. The operation consumes active and daily activation capacity.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
suggested_prompt_iduuid

Suggested Prompt identifier.

Required
Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]prompts:Prompt[]
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions transitioned to tracked.

promptsPrompt[]

Prompts created from the suggestions.

Object

Prompt

iduuid

Unique prompt identifier.

topic_iduuid

Topic that contains the prompt.

topic_namestring

Current name of the containing topic.

contentstring

Question sent to configured AI models. Maximum 20,000 characters.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Stable snake_case intent category.

city_overridestring | null

Prompt-specific city. Null means the city is inherited from the selected scope.

country_overridestring | null

Prompt-specific country. Null means the country is inherited from the selected scope; present together with country_code_override.

country_code_overridestring | null

Prompt-specific uppercase ISO 3166-1 alpha-2 country code. Null means the code is inherited; present together with country_override.

archived_atdatetime | null

Archive time. Null means the prompt is active.

created_atdatetime

Prompt creation time in ISO 8601 format.

metricsPromptMetrics | null

Visibility metrics for the requested date and model filters.

Object

PromptMetrics

primary_mentionsinteger

Responses that mentioned the primary tracked brand.

visibility_percentagenumber

Share of responses that mentioned the primary tracked brand.

visibility_trend_ppnumber | null

Percentage-point change from the preceding equal-length period.

average_positionnumber | null

Average 1-based primary-brand position when mentioned.

position_trendnumber | null

Average-position change from the preceding period.

average_position_trendnumber | null

Change in average position from the preceding comparison window.

average_sentimentnumber | null

Average primary-brand sentiment score.

sentiment_countsSentimentCounts

Response counts keyed by negative, neutral, and positive.

citationsinteger

Citation occurrences across matching responses.

competitor_mentionsRecord<string, integer>

Mention counts keyed by tracked competitor name.

Object

SentimentCounts

negativeinteger

Negative responses.

neutralinteger

Neutral responses.

positiveinteger

Positive responses.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/track' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "tracked",
      "tracked_prompt_id": "4de5e484-ce6a-4e45-ad7c-bd48db2549af",
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": "2026-07-31T10:10:00Z",
      "dismissed_at": null,
      "expired_at": null
    }
  ],
  "prompts": [
    {
      "id": "4de5e484-ce6a-4e45-ad7c-bd48db2549af",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "Which platforms help brands measure visibility in AI answers?",
      "category": "organic_search",
      "city_override": null,
      "country_override": null,
      "country_code_override": null,
      "archived_at": null,
      "created_at": "2026-07-20T08:35:00Z",
      "metrics": 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_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.

POST
/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/dismiss

Dismisses one visible suggestion without creating a prompt. Dismissed content remains fingerprinted to prevent the same suggestion from reappearing.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
suggested_prompt_iduuid

Suggested Prompt identifier.

Required
Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions transitioned to dismissed.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/dismiss' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "dismissed",
      "tracked_prompt_id": null,
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": null,
      "dismissed_at": "2026-07-31T10:12:00Z",
      "expired_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_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.