# Suggested prompts

Source: https://ceyo.ai/docs/signal/suggested-prompts

### Suggested prompts

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

**Scope:** Project

### List suggested prompts

`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.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |

#### Query parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `q` | string | Optional | Search suggestion content, reason, and topic name. |
| `status` | suggested \| tracked \| dismissed \| expired | Optional; Default: suggested | Suggestion lifecycle state to return. |
| `page` | integer | Optional; Default: 1 | 1-based page number. |
| `per_page` | integer | Optional; Default: 20 | Suggestions per page. Maximum: 100. |

#### Response envelope

`project_id`:**uuid**`suggested_prompts`:**SuggestedPrompt\[\]**`pagination`:**Pagination**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `suggested_prompts` | SuggestedPrompt\[\] |  | Suggestions matching the selected status and search. |
| `pagination` | Pagination |  | Suggestion pagination metadata. |

#### SuggestedPrompt

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Suggested prompt identifier. |
| `topic_id` | uuid |  | Existing topic selected for the suggestion. |
| `topic_name` | string |  | Current name of the selected topic. |
| `content` | string |  | Suggested prompt question. |
| `category` | general \| organic\_search \| brand\_sentiment \| competitor\_comparison |  | Prompt intent category. |
| `reason` | string \| null |  | Evidence-based reason the prompt was suggested. |
| `status` | suggested \| tracked \| dismissed \| expired |  | Suggestion lifecycle state. |
| `tracked_prompt_id` | uuid \| null |  | Prompt created when this suggestion was tracked. |
| `created_at` | datetime |  | Suggestion creation time. |
| `tracked_at` | datetime \| null |  | Time the suggestion became a tracked prompt. |
| `dismissed_at` | datetime \| null |  | Time the suggestion was dismissed. |
| `expired_at` | datetime \| null |  | Time the suggestion was automatically expired. |

#### Pagination

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `page` | integer |  | Current 1-based page. |
| `per_page` | integer |  | Records requested per page. |
| `total` | integer |  | Total records matching the filters. |
| `total_pages` | integer |  | Total available pages. |

#### Request and response

```curl
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_...'
```

```json
{
  "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
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request \| invalid\_date\_range \| range\_too\_large |  | A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months. |
| `401` | invalid\_api\_key |  | Authorization is absent or invalid. |
| `403` | forbidden |  | The API key cannot manage this visibility scope. |
| `404` | not\_found |  | The project, location, or suggested prompt was not found. |
| `409` | conflict |  | The requested lifecycle operation conflicts with current state. |
| `422` | validation\_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. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Track suggested prompt

`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.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |
| `suggested_prompt_id` | uuid | Required | Suggested Prompt identifier. |

#### SuggestedPrompt

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Suggested prompt identifier. |
| `topic_id` | uuid |  | Existing topic selected for the suggestion. |
| `topic_name` | string |  | Current name of the selected topic. |
| `content` | string |  | Suggested prompt question. |
| `category` | general \| organic\_search \| brand\_sentiment \| competitor\_comparison |  | Prompt intent category. |
| `reason` | string \| null |  | Evidence-based reason the prompt was suggested. |
| `status` | suggested \| tracked \| dismissed \| expired |  | Suggestion lifecycle state. |
| `tracked_prompt_id` | uuid \| null |  | Prompt created when this suggestion was tracked. |
| `created_at` | datetime |  | Suggestion creation time. |
| `tracked_at` | datetime \| null |  | Time the suggestion became a tracked prompt. |
| `dismissed_at` | datetime \| null |  | Time the suggestion was dismissed. |
| `expired_at` | datetime \| null |  | Time the suggestion was automatically expired. |

#### Response envelope

`project_id`:**uuid**`suggested_prompts`:**SuggestedPrompt\[\]**`prompts`:**Prompt\[\]**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `suggested_prompts` | SuggestedPrompt\[\] |  | Suggestions transitioned to tracked. |
| `prompts` | Prompt\[\] |  | Prompts created from the suggestions. |

#### Prompt

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Unique prompt identifier. |
| `topic_id` | uuid |  | Topic that contains the prompt. |
| `topic_name` | string |  | Current name of the containing topic. |
| `content` | string |  | Question sent to configured AI models. Maximum 20,000 characters. |
| `category` | general \| organic\_search \| brand\_sentiment \| competitor\_comparison |  | Stable snake\_case intent category. |
| `city_override` | string \| null |  | Prompt-specific city. Null means the city is inherited from the selected scope. |
| `country_override` | string \| null |  | Prompt-specific country. Null means the country is inherited from the selected scope; present together with country\_code\_override. |
| `country_code_override` | string \| null |  | Prompt-specific uppercase ISO 3166-1 alpha-2 country code. Null means the code is inherited; present together with country\_override. |
| `archived_at` | datetime \| null |  | Archive time. Null means the prompt is active. |
| `created_at` | datetime |  | Prompt creation time in ISO 8601 format. |
| `metrics` | PromptMetrics \| null |  | Visibility metrics for the requested date and model filters. |

#### PromptMetrics

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `primary_mentions` | integer |  | Responses that mentioned the primary tracked brand. |
| `visibility_percentage` | number |  | Share of responses that mentioned the primary tracked brand. |
| `visibility_trend_pp` | number \| null |  | Percentage-point change from the preceding equal-length period. |
| `average_position` | number \| null |  | Average 1-based primary-brand position when mentioned. |
| `position_trend` | number \| null |  | Average-position change from the preceding period. |
| `average_position_trend` | number \| null |  | Change in average position from the preceding comparison window. |
| `average_sentiment` | number \| null |  | Average primary-brand sentiment score. |
| `sentiment_counts` | SentimentCounts |  | Response counts keyed by negative, neutral, and positive. |
| `citations` | integer |  | Citation occurrences across matching responses. |
| `competitor_mentions` | Record<string, integer> |  | Mention counts keyed by tracked competitor name. |

#### SentimentCounts

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `negative` | integer |  | Negative responses. |
| `neutral` | integer |  | Neutral responses. |
| `positive` | integer |  | Positive responses. |

#### Request and response

```curl
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_...'
```

```json
{
  "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
    }
  ]
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request \| invalid\_date\_range \| range\_too\_large |  | A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months. |
| `401` | invalid\_api\_key |  | Authorization is absent or invalid. |
| `403` | forbidden |  | The API key cannot manage this visibility scope. |
| `404` | not\_found |  | The project, location, or suggested prompt was not found. |
| `409` | conflict |  | The requested lifecycle operation conflicts with current state. |
| `422` | validation\_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. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Dismiss suggested prompt

`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.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |
| `suggested_prompt_id` | uuid | Required | Suggested Prompt identifier. |

#### SuggestedPrompt

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Suggested prompt identifier. |
| `topic_id` | uuid |  | Existing topic selected for the suggestion. |
| `topic_name` | string |  | Current name of the selected topic. |
| `content` | string |  | Suggested prompt question. |
| `category` | general \| organic\_search \| brand\_sentiment \| competitor\_comparison |  | Prompt intent category. |
| `reason` | string \| null |  | Evidence-based reason the prompt was suggested. |
| `status` | suggested \| tracked \| dismissed \| expired |  | Suggestion lifecycle state. |
| `tracked_prompt_id` | uuid \| null |  | Prompt created when this suggestion was tracked. |
| `created_at` | datetime |  | Suggestion creation time. |
| `tracked_at` | datetime \| null |  | Time the suggestion became a tracked prompt. |
| `dismissed_at` | datetime \| null |  | Time the suggestion was dismissed. |
| `expired_at` | datetime \| null |  | Time the suggestion was automatically expired. |

#### Response envelope

`project_id`:**uuid**`suggested_prompts`:**SuggestedPrompt\[\]**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `suggested_prompts` | SuggestedPrompt\[\] |  | Suggestions transitioned to dismissed. |

#### Request and response

```curl
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_...'
```

```json
{
  "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
    }
  ]
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request \| invalid\_date\_range \| range\_too\_large |  | A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months. |
| `401` | invalid\_api\_key |  | Authorization is absent or invalid. |
| `403` | forbidden |  | The API key cannot manage this visibility scope. |
| `404` | not\_found |  | The project, location, or suggested prompt was not found. |
| `409` | conflict |  | The requested lifecycle operation conflicts with current state. |
| `422` | validation\_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. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |