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

Topics

Create and manage topic groups used to organize prompts for the selected project or location.

API scopeThese endpoints are available at both scopes.
Choose the resource whose data you want to manage.Learn about scopes →

Your selection updates every endpoint path, path parameter, and example on this page.

GET
project/projects/{project_id}/visibility/topics

Returns paginated topics in the selected project, ordered deterministically by created_at, then id.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Topics per page. Maximum: 100.

OptionalDefault: 25
Response

Response envelope

project_id:uuidtopics:Topic[]pagination:Pagination
project_iduuid

Resolved Ceyo project identifier.

topicsTopic[]

Topics ordered by created_at, then id.

paginationPagination

Topic pagination metadata.

Object

Topic

iduuid

Unique topic identifier.

namestring

Customer-facing topic name; maximum 200 characters and case-insensitively unique within this visibility scope.

created_atdatetime

Topic creation time in ISO 8601 format.

updated_atdatetime

Time the topic was last updated.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/topics?page=1&per_page=25' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "topics": [
    {
      "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "name": "AI visibility platforms",
      "created_at": "2026-07-20T08:30:00Z",
      "updated_at": "2026-07-20T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records requested per page.

totalinteger

Total records matching the filters.

total_pagesinteger

Total available pages.

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 topic 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
project/projects/{project_id}/visibility/topics

Creates a topic in the selected project. Topic names should represent a durable customer question area rather than an individual query.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Request

Request body

namestring

Required topic name; maximum 200 characters and case-insensitively unique within the scope.

Response

Response envelope

project_id:uuidtopic:Topic
project_iduuid

Resolved Ceyo project identifier.

topicTopic

Created topic.

Object

Topic

iduuid

Unique topic identifier.

namestring

Customer-facing topic name; maximum 200 characters and case-insensitively unique within this visibility scope.

created_atdatetime

Topic creation time in ISO 8601 format.

updated_atdatetime

Time the topic was last updated.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/topics' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{"name":"AI visibility platforms"}'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "topic": {
    "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
    "name": "AI visibility platforms",
    "created_at": "2026-07-20T08:30:00Z",
    "updated_at": "2026-07-20T08:30:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "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 topic 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
project/projects/{project_id}/visibility/topics/{topic_id}

Returns one topic from the selected project. Use the prompt list with topic_ids to retrieve its prompts and metrics.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
topic_iduuid

Topic identifier.

Required
Response

Response envelope

project_id:uuidtopic:Topic
project_iduuid

Resolved Ceyo project identifier.

topicTopic

Requested topic.

Object

Topic

iduuid

Unique topic identifier.

namestring

Customer-facing topic name; maximum 200 characters and case-insensitively unique within this visibility scope.

created_atdatetime

Topic creation time in ISO 8601 format.

updated_atdatetime

Time the topic was last updated.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/topics/{topic_id}' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "topic": {
    "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
    "name": "AI visibility platforms",
    "created_at": "2026-07-20T08:30:00Z",
    "updated_at": "2026-07-20T08:30:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "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 topic 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
project/projects/{project_id}/visibility/topics/{topic_id}

Starts irreversible asynchronous deletion of a topic and its dependent visibility data. This is not an archive operation.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
topic_iduuid

Topic identifier.

Required
IrreversibleTopic deletion is asynchronous and permanent. Archive individual prompts when they may need to be restored later.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/topics/{topic_id}' \
  --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 topic 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.