Engines

The Engines API manages the AI engines a project tracks. An engine belongs to the whole project rather than to a single location: it is tracked in every location and language of the project. Where the project is tracked is managed with Locations.

Using the SE Visible API, you can:

• list the engines a project tracks
• add an engine to a project, or restore one removed earlier together with its collected data
• replace the project’s whole engine set in one request
• remove an engine from a project

Engine types are listed in the Reference.

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

List project engines

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

Returns the AI engines a project tracks, one entry per engine type. An entry carries no location, because an engine is tracked in all of the project’s locations.

Request parameters

Path parameters

Request example

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

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a JSON array of the project’s engines.

Response example

[

  { "engine_type": "chatgpt" },

  { "engine_type": "google_gemini" }

]

Add an engine

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

Adds an AI engine to every location and language the project tracks, and starts tracking each location’s prompts with it.

Note:

• An engine tracked in only some locations is completed. The request is rejected only when the engine is already tracked everywhere: it then returns 422 with error_code engine_already_added.
• Re-adding an engine that was removed earlier restores it together with the results, mentions and sources collected before the removal. A location that was removed stays removed and does not get the engine.

Request parameters

Path parameters

Request body

Request example

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/engines' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "engine_type": "chatgpt"

  }'

Response parameters

If successful, the server returns 201 Created with the added engine.

Response example

{

  "engine_type": "chatgpt"

}

Replace the engine set

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

Replaces the set of engines a project tracks with the given list in one atomic request. Engines missing from the project are added, or restored with their previously collected results, mentions and sources. Engines absent from the list are removed.

Note:

• The list applies to every location the project tracks. An engine tracked in only some locations is completed, so the request also evens out an uneven set and is idempotent.
• The list cannot be empty: a project always keeps at least one engine. An empty list, an unknown engine type or a duplicate entry returns 422.

Request parameters

Path parameters

Request body

Request example

curl -X PUT 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/engines' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "engines": [

      { "engine_type": "chatgpt" },

      { "engine_type": "google_ai_overview" }

    ]

  }'

Response parameters

If successful, the server returns a JSON array with the resulting set of project engines.

Response example

[

  { "engine_type": "chatgpt" },

  { "engine_type": "google_ai_overview" }

]

Remove an engine

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

Removes an engine from the whole project, in every location and language it was tracked in. Its prompt links, results, mentions and sources disappear from the project but are retained, and come back if you add the engine again.

Note:

• An engine that would leave a location without any engine, including the project’s last engine, cannot be removed. Attempting to do so returns 422 with error_code cannot_remove_last_engine.
• An engine type the project does not track, including an unknown one, returns 404.

Request parameters

Path parameters

Request example

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

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

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