AI Search: deprecate three prompts filters and document the new data source

[mikhail-liubushkin]

Draft: do not merge before the cut-over date. <CUTOVER_DATE> is a literal placeholder and must be replaced with the real date before this is merged.

What

Updates the AI Search part of openapi/data-api.yaml (and the generated openapi/data-api.json) for the move to the new AI Search data source and the prompts filter cut-over.

/v1/ai-search/prompts-by-target, /v1/ai-search/prompts-by-brand

• filter[volume][from|to], filter[keyword_count][from|to] and filter[characters_count][from|to] are marked deprecated: true with the description "Removed on <CUTOVER_DATE>; requests that use it get 400 unsupported filter." The operation description says the same.
• limit documents maximum: 1000. A larger value gets a 400.
• A 400 response is documented: limit above 1000, or a filter that is no longer supported.
• The 200 description lists the data changes since 2026-09-29: prompts[].volume is null for engine=ai-overview and 0 for the LLM engines, and date is the current month.

/v1/ai-search/overview/aggregated/time-series, /v1/ai-search/overview/by-engine/time-series

The 200 description lists the data changes since 2026-09-29:

• summary.average_position is always null.
• time_series.organic_traffic, time_series.overall_traffic and time_series.average_position are empty arrays.
• summary.brand_presence matches the brand as a recognized entity, not as text.
• summary.*.previous is the previous monthly snapshot, and change_absolute / change_percent are computed from it. Before this change, previous was always null and the change was reported as the current value and 100%.

/v1/ai-search/overview/leaderboard

• The 200 description says that brand_presence matches the brand as an entity.

Not changed

• /v1/domain/aio/overview, /keywords-by-target and /keywords-by-brand are not in this spec, so there is nothing to mark as removed (410).
• The responses still have no schemas (application/json: {}), as before. That is why the data changes are described in the response descriptions.

Validation

• redocly lint openapi/data-api.yaml: valid. Warnings went from 88 to 86 because the new 400 responses satisfy operation-4xx-response.
• The CI "JSON matches YAML" check passes. data-api.json was regenerated from the YAML with the file's existing formatting: 2-space indent, ASCII escapes, no trailing newline.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wgf1DkCuX1WDHgjtcpzQ4y

[linear-code]

DAT-917