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

Prompts

Create and manage the monitored questions used for visibility tracking.

ProjectLocation
Model availabilityPrompt create, bulk create, and restore validate the effective country, including country overrides, against every package model. Unsupported combinations return 422 unsupported_model_country_combination with the unsupported model keys in the error details. Prompt content is limited to 500 characters when Claude is enabled; longer content returns 422 prompt_model_limit_exceeded.
GET
/projects/{project_id}/visibility/prompts

Returns paginated prompts and visibility metrics for the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

startdate

First metrics date in YYYY-MM-DD format. The inclusive range may span at most 3 months.

OptionalDefault: 29 days before end
enddate

Last metrics date in YYYY-MM-DD format. The inclusive range may span at most 3 months.

OptionalDefault: Today
modelsstring

Comma-separated or repeated model keys.

OptionalDefault: All enabled models
topic_idsstring

Comma-separated or repeated topic UUIDs.

Optional
competitor_idsstring

Tracked competitor UUIDs that must be mentioned.

Optional
sentimentsstring

Comma-separated negative, neutral, or positive labels.

Optional
categorygeneral | organic_search | brand_sentiment | competitor_comparison

Restrict prompts to one category.

Optional
qstring

Search prompt content and topic names.

Optional
statusactive | archived

Select active prompts or archived prompts.

OptionalDefault: active
sortcreated_at | prompt | topic | visibility | position | volume

Field used to order the result.

OptionalDefault: created_at
sort_directionasc | desc

Sort direction.

OptionalDefault: desc
pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Prompts per page. Maximum: 100.

OptionalDefault: 25
Response

Response envelope

project_id:uuidprompts:Prompt[]start:dateend:datemodels:string[]pagination:Pagination
project_iduuid

Resolved Ceyo project identifier.

promptsPrompt[]

Paginated prompts matching the filters.

startdate

Resolved metrics start date.

enddate

Resolved metrics end date.

modelsstring[]

Model keys included in metric calculations.

paginationPagination

Prompt pagination metadata.

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.

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/prompts?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity&status=active&page=1' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "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": {
        "primary_mentions": 8,
        "visibility_percentage": 57.14,
        "visibility_trend_pp": 7.14,
        "average_position": 2.25,
        "position_trend": -0.5,
        "average_position_trend": -0.5,
        "average_sentiment": 7.6,
        "sentiment_counts": {
          "negative": 1,
          "neutral": 4,
          "positive": 9
        },
        "citations": 22,
        "competitor_mentions": {
          "Example competitor": 6
        }
      }
    }
  ],
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": [
    "chatgpt",
    "perplexity"
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 36,
    "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": "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 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/prompts

Creates and activates one prompt for visibility tracking across the enabled models.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Request

Request body

topic_iduuid

Topic in this scope. Required when creating a prompt.

contentstring

Prompt question. Required; maximum 20,000 characters.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt category. Defaults to general when creating.

city_overridestring | null

Optional create-only city override; maximum 200 characters. Omit or send null to inherit the scope city.

country_overridestring | null

Country name for a location override; must be provided with country_code_override. Maximum 200 characters.

country_code_overridestring | null

Uppercase two-letter code for a location override; must be provided with country_override.

Location overridecountry_override and country_code_override must be supplied together. city_override is optional. Effective geography combines these values with the scope defaults. Language comes from the selected scope.
Response

Response envelope

project_id:uuidprompt:Prompt
project_iduuid

Resolved Ceyo project identifier.

promptPrompt

Created and activated prompt.

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/prompts' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{"topic_id":"ab20526b-6bb2-436c-8c93-5bf77ea43848","content":"Which platforms help brands measure visibility in AI answers?","category":"organic_search"}'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "prompt": {
    "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 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/prompts/bulk_create

Creates and activates up to 100 prompts atomically. Any invalid row or capacity failure rejects the entire request.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Request

Request body

promptsPromptInput[]

Required array containing 1–100 prompt rows.

Request

PromptInput

topic_iduuid

Topic in this scope. Required when creating a prompt.

contentstring

Prompt question. Required; maximum 20,000 characters.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt category. Defaults to general when creating.

city_overridestring | null

Optional create-only city override; maximum 200 characters. Omit or send null to inherit the scope city.

country_overridestring | null

Country name for a location override; must be provided with country_code_override. Maximum 200 characters.

country_code_overridestring | null

Uppercase two-letter code for a location override; must be provided with country_override.

Location overrideEach row must supply country_override and country_code_override together. city_override is optional. Effective geography combines these values with the scope defaults; language is inherited.
Response

Response envelope

project_id:uuidprompts:Prompt[]
project_iduuid

Resolved Ceyo project identifier.

promptsPrompt[]

Created and activated prompts in request order.

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/prompts/bulk_create' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{"prompts":[{"topic_id":"ab20526b-6bb2-436c-8c93-5bf77ea43848","content":"Which platforms help brands measure visibility in AI answers?","category":"organic_search"},{"topic_id":"ab20526b-6bb2-436c-8c93-5bf77ea43848","content":"How do AI visibility platforms compare?","category":"competitor_comparison"}]}'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "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
    },
    {
      "id": "ab7d6157-ca42-4d43-b02c-edeea5911475",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "How do AI visibility platforms compare?",
      "category": "competitor_comparison",
      "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 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.

GET
/projects/{project_id}/visibility/prompts/{prompt_id}

Returns one active or archived prompt in the selected project, with metrics for the requested period and enabled-model context.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
prompt_iduuid

Prompt identifier.

Required
Parameters

Query parameters

startdate

First metrics date in YYYY-MM-DD format. The inclusive range may span at most 3 months.

OptionalDefault: 29 days before end
enddate

Last metrics date in YYYY-MM-DD format. The inclusive range may span at most 3 months.

OptionalDefault: Today
modelsstring

Comma-separated or repeated model keys.

OptionalDefault: All enabled models
Response

Response envelope

project_id:uuidprompt:Promptstart:dateend:datemodels:string[]
project_iduuid

Resolved Ceyo project identifier.

promptPrompt

Requested prompt and metrics.

startdate

Resolved metrics start.

enddate

Resolved metrics end.

modelsstring[]

Models included in metrics.

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 GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/prompts/{prompt_id}?start=2026-07-24&end=2026-07-30' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "prompt": {
    "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": {
      "primary_mentions": 8,
      "visibility_percentage": 57.14,
      "visibility_trend_pp": 7.14,
      "average_position": 2.25,
      "position_trend": -0.5,
      "average_position_trend": -0.5,
      "average_sentiment": 7.6,
      "sentiment_counts": {
        "negative": 1,
        "neutral": 4,
        "positive": 9
      },
      "citations": 22,
      "competitor_mentions": {
        "Example competitor": 6
      }
    }
  },
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": [
    "chatgpt",
    "perplexity"
  ]
}
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 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.

DELETE
/projects/{project_id}/visibility/prompts/{prompt_id}

Archives an active prompt and stops it consuming active capacity. Historical response data remains available. A successful archive has no response body.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
prompt_iduuid

Prompt identifier.

Required
Object

Response

204No Content

Prompt was archived successfully.

Reversible archiveArchive hides a prompt from active monitoring but preserves its data. Use restore to activate it again. Permanent deletion is a separate, irreversible endpoint.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/prompts/{prompt_id}' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
HTTP/1.1 204 No Content
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 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/prompts/{prompt_id}/restore

Restores and reactivates an archived prompt after checking active capacity only. Restore does not consume daily activations and does not schedule a visibility run.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
prompt_iduuid

Prompt identifier.

Required
Response

Response envelope

project_id:uuidprompt:Prompt
project_iduuid

Resolved Ceyo project identifier.

promptPrompt

Restored and reactivated prompt.

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/prompts/{prompt_id}/restore' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "prompt": {
    "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 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.

DELETE
/projects/{project_id}/visibility/prompts/{prompt_id}/permanent

Starts irreversible asynchronous deletion of a prompt and its dependent visibility data. Archive the prompt instead if it may be needed again.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
prompt_iduuid

Prompt identifier.

Required
Irreversible deleteThe request returns before background deletion completes.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/prompts/{prompt_id}/permanent' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
HTTP/1.1 202 Accepted
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 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.