Topics
The Topics API manages the topics inside a project. Topics group related prompts so you can organise prompts you track and slice visibility metrics by topic. Each project has one default topic that is created automatically.
Using the SE Visible API, you can:
- create one or more topics in a project at once
- rename an existing topic
- delete a topic and the prompts grouped under it
All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.
Create topics
POST https://api.seranking.com/v1/se-visible/projects/{project_id}/topics
Creates one or more topics in a project. Pass the titles you want to add and the server creates a topic for each one, returning the created topics.
Request parameters
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | String (UUID) | Yes | UUID of the project. |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| titles | Array of String | Yes | Topic titles to create. At least one title, each non-empty and maximum 255 characters. |
Request example
curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/topics' \
-H 'Authorization: Token YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"titles": ["Artificial Intelligence", "Machine Learning"]
}'Response parameters
If successful, the server returns a JSON array of the created topics.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Topic ID. |
| report_id | String (UUID) | UUID of the project the topic belongs to. |
| title | String | Topic title. |
| is_default | Boolean or null | true only for the project’s default topic, null for every other topic. Returned only for a topic that already existed. |
| created_at | String (datetime) or null | When the topic was created. |
| updated_at | String (datetime) or null | When the topic was last updated. |
| deleted_at | String (datetime) or null | When the topic was deleted, or null. Returned only for a topic that already existed. |
Response example
[
{
"id": 123,
"report_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Artificial Intelligence",
"created_at": "2023-12-15T10:30:00.000000Z",
"updated_at": "2023-12-15T10:30:00.000000Z"
},
{
"id": 124,
"report_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Machine Learning",
"created_at": "2023-12-15T10:30:00.000000Z",
"updated_at": "2023-12-15T10:30:00.000000Z"
}
]Update a topic title
PUT https://api.seranking.com/v1/se-visible/projects/{project_id}/topics/{topic_id}
Updates the title of a topic in a project.
Note:
- The default topic cannot be updated.
Request parameters
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | String (UUID) | Yes | UUID of the project. |
| topic_id | Integer | Yes | Topic ID to update. |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | String | Yes | New title for the topic. Minimum 1 character, maximum 255 characters. |
Request example
curl -X PUT 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/topics/123' \
-H 'Authorization: Token YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Artificial Intelligence"
}'Response parameters
If successful, the server returns the updated topic.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Topic ID. |
| report_id | String (UUID) | UUID of the project the topic belongs to. |
| title | String | Topic title. |
| is_default | Boolean or null | true only for the project’s default topic, null for every other topic. Returned only for a topic that already existed. |
| created_at | String (datetime) or null | When the topic was created. |
| updated_at | String (datetime) or null | When the topic was last updated. |
| deleted_at | String (datetime) or null | When the topic was deleted, or null. Returned only for a topic that already existed. |
Response example
{
"id": 123,
"report_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Artificial Intelligence",
"is_default": null,
"created_at": "2023-12-15T10:30:00.000000Z",
"updated_at": "2023-12-15T11:05:00.000000Z",
"deleted_at": null
}Delete a topic
DELETE https://api.seranking.com/v1/se-visible/projects/{project_id}/topics/{topic_id}
Deletes a topic and its associated prompts from a project.
Request parameters
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | String (UUID) | Yes | UUID of the project. |
| topic_id | Integer | Yes | Topic ID to delete. |
Request example
curl -X DELETE 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/topics/123' \
-H 'Authorization: Token YOUR_API_KEY'Response parameters
If successful, the server returns 204 No Content with an empty body.
