add_topic

Add a new visibility topic with optional queries. Topics group related search queries. Queries have a reach level that indicates how closely they relate to the brand.

Authentication: Required

Parameters

Parameter	Type	Required	Description
`syntheticId`	`integer`	Yes	The agent ID to add the topic to.
`name`	`string`	Yes	Topic name, e.g., `"AI Content Quality"` or `"Competitor Comparisons"`.
`description`	`string`	No	Description of what this topic covers.
`queries`	`array`	No	Queries to add to this topic.
`queries[].query`	`string`	Yes (within array)	The search query text.
`queries[].reachLevel`	`"core" \| "adjacent" \| "aspirational" \| "visionary"`	No	How closely this query relates to the brand. Defaults to `"core"`.

Example call

{
  "syntheticId": 1234,
  "name": "Competitor Comparisons",
  "description": "Queries comparing Example with competitors",
  "queries": [
    { "query": "Example vs CompetitorA", "reachLevel": "core" },
    { "query": "Best alternatives to CompetitorA", "reachLevel": "adjacent" },
    { "query": "AI visibility tool comparison 2026", "reachLevel": "adjacent" }
  ]
}

Response

{
  "success": true,
  "syntheticId": 1234,
  "topic": {
    "id": "topic-new",
    "name": "Competitor Comparisons",
    "description": "Queries comparing Example with competitors",
    "isActive": true,
    "queries": [
      { "id": "q-10", "query": "Example vs CompetitorA", "reachLevel": "core" },
      { "id": "q-11", "query": "Best alternatives to CompetitorA", "reachLevel": "adjacent" },
      { "id": "q-12", "query": "AI visibility tool comparison 2026", "reachLevel": "adjacent" }
    ]
  }
}

New topics and queries are automatically included in the next visibility scan.

Parameters

Example call

Response

On this page