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. |
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. |
| title | String | Topic title. |
| is_default | Boolean | true for the project’s default topic, false otherwise. |
Response example
[
{ "id": 123, "title": "Artificial Intelligence", "is_default": false },
{ "id": 124, "title": "Machine Learning", "is_default": false }
]
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. 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. |
| title | String | Topic title. |
| is_default | Boolean | true for the project’s default topic, false otherwise. |
Response example
{
"id": 123,
"title": "Artificial Intelligence",
"is_default": false
}
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.
