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
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: 6 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: 6 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.