Projects

The Projects API creates and manages SE Visible projects. A project tracks one primary brand with a domain, a country and language, across a set of AI models. Everything else in SE Visible (brands, topics, prompts, results, and sources) hangs off a project.

Using the SE Visible API, you can:

• list every project in your organisation with its domain, competitive brands, status, and tracked AI models
• create a new project and have it processed asynchronously to generate prompts and collect data
• read a project’s full details, including processing progress, topics, check dates, and tracked competitor brands
• delete a project (soft delete, can be restored)

All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.

List projects

GET https://api.seranking.com/v1/se-visible/projects

Returns all projects belonging to the authenticated user’s organisation. Each project includes its domain, tracked brand names, status, and the AI models it runs against.

Request parameters

This endpoint takes no parameters.

Request example

curl -X GET 'https://api.seranking.com/v1/se-visible/projects' \
  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a JSON array of project objects.

Response example

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "https://lavazza.com",
    "brand_names": ["Lavazza"],
    "created_at": "2023-12-15 10:30:00",
    "checked_at": "2023-12-15 11:45:00",
    "status": "success",
    "models": [
      { "model_type": "chatgpt", "country_code": "US" }
    ]
  }
]

Create project

POST https://api.seranking.com/v1/se-visible/projects

Creates a new project for tracking brand visibility across AI models.

Note:

• A new project is queued and processed asynchronously to generate prompts and collect data. The response returns the project id immediately, before processing finishes.
• Poll Get project details and read check.processed_percent (0 to 100) and project.status (queued, processing, success, error) to track progress.

Request parameters

Request body

Request example

curl -X POST 'https://api.seranking.com/v1/se-visible/projects' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "https://lavazza.com",
    "country_code": "US",
    "lang_code": "en",
    "brand_names": ["Lavazza"],
    "topics": [
      "Ground Coffee",
      "Whole Bean Coffee",
      "Espresso Machines",
      "Coffee Makers",
      "Accessories"
    ]
  }'

Response parameters

If successful, the server returns the UUID of the newly created project.

Response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Get project details

GET https://api.seranking.com/v1/se-visible/projects/{project_id}

Returns detailed information about a single project: its metadata, check processing progress, the topics being tracked, available historical check dates, the next scheduled check, and the competitor brands attached to it.

Request parameters

Path parameters

Request example

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a project details object.

Response example

{
  "project": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "https://lavazza.com",
    "brand_names": ["Lavazza"],
    "created_at": "2023-12-15 10:30:00",
    "checked_at": "2023-12-15 11:45:00",
    "status": "success",
    "models": [
      { "model_type": "chatgpt", "country_code": "US" },
      { "model_type": "google_ai_mode", "country_code": "US" }
    ]
  },
  "check": {
    "processed_percent": 75
  },
  "topics": [
    { "id": 1, "title": "Default", "is_default": true, "prompts_count": 0 },
    { "id": 2, "title": "Ground Coffee", "is_default": false, "prompts_count": 10 },
    { "id": 3, "title": "Whole Bean Coffee", "is_default": false, "prompts_count": 8 }
  ],
  "check_dates": ["2023-12-15", "2023-12-14", "2023-12-13"],
  "next_check_date": "2023-12-22 10:00:00",
  "tracked_brands": [
    { "brand_id": 10, "brand_name": "Illy", "domain": "https://illy.com" },
    { "brand_id": 11, "brand_name": "Nespresso", "domain": null }
  ],
  "has_unparsed_prompts": false
}

Delete a project

DELETE https://api.seranking.com/v1/se-visible/projects/{project_id}

Soft-deletes a project from your organisation. The project is removed from active use but can be restored if needed.

Request parameters

Path parameters

Request example

curl -X DELETE 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns 204 No Content with an empty body.