Skip to content

Commit 9b49b25

Browse files
[feat/serenity-init]: codebase alignment
1 parent 76d6dbc commit 9b49b25

26 files changed

Lines changed: 1123 additions & 760 deletions

docs/index.html

Lines changed: 44 additions & 44 deletions
Large diffs are not rendered by default.

docs/openapi/ai-visibility-api.yaml

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# AI Visibility (Semrush gRPC proxy) – 22 GET endpoints
22
# All endpoints live under /llmo/ai-visibility/* and proxy to Semrush gRPC.
3-
# Responses include an sr_filters block with available markets and models.
3+
# Responses include an srFilters block with available markets and models.
44

55
# ── shared parameter fragments ──────────────────────────────────────────
66
x-ai-vis-domain: &domainParam
@@ -34,10 +34,10 @@ x-ai-vis-engine: &engineParam
3434
name: engine
3535
in: query
3636
required: false
37-
description: LLM engine slug (`chatgpt`, `gemini`, `google_ai_mode`, `google_ai_overview`). Omit or `all` for all models.
37+
description: LLM engine slug (`chatgpt`, `gemini`, `googleAiMode`, `googleAiOverview`). Omit or `all` for all models.
3838
schema:
3939
type: string
40-
enum: [chatgpt, gemini, google_ai_mode, google_ai_overview, all]
40+
enum: [chatgpt, gemini, googleAiMode, googleAiOverview, all]
4141
example: chatgpt
4242

4343
x-ai-vis-limit: &limitParam
@@ -71,7 +71,7 @@ x-ai-vis-month: &monthParam
7171
example: '2026-01'
7272

7373
x-ai-vis-window-months: &windowMonthsParam
74-
name: window_months
74+
name: windowMonths
7575
in: query
7676
required: false
7777
description: Number of months to include in date-range aggregations
@@ -81,7 +81,7 @@ x-ai-vis-window-months: &windowMonthsParam
8181
example: 6
8282

8383
x-ai-vis-search-query: &searchQueryParam
84-
name: search_query
84+
name: searchQuery
8585
in: query
8686
required: true
8787
description: Full-text search query for topic research
@@ -90,7 +90,7 @@ x-ai-vis-search-query: &searchQueryParam
9090
example: coffee
9191

9292
x-ai-vis-topic-id: &topicIdParam
93-
name: topic_id
93+
name: topicId
9494
in: query
9595
required: true
9696
description: Topic identifier
@@ -384,14 +384,14 @@ ai-visibility-competitors-metrics:
384384
- *countryParam
385385
- *regionParam
386386
- *engineParam
387-
- name: gap_snapshot_date
387+
- name: gapSnapshotDate
388388
in: query
389389
required: false
390390
description: Pin to a specific snapshot date (`YYYY-MM-DD`)
391391
schema:
392392
type: string
393393
pattern: '^\d{4}-\d{2}-\d{2}$'
394-
- name: metrics_snapshot_date
394+
- name: metricsSnapshotDate
395395
in: query
396396
required: false
397397
description: Pin to a specific metrics snapshot date (`YYYY-MM-DD`)
@@ -425,7 +425,7 @@ ai-visibility-competitors-gap-topics:
425425
- *engineParam
426426
- *limitParam
427427
- *offsetParam
428-
- name: gap_kinds
428+
- name: gapKinds
429429
in: query
430430
required: false
431431
description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
@@ -459,7 +459,7 @@ ai-visibility-competitors-gap-source-domains:
459459
- *engineParam
460460
- *limitParam
461461
- *offsetParam
462-
- name: gap_kinds
462+
- name: gapKinds
463463
in: query
464464
required: false
465465
description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
@@ -495,14 +495,14 @@ ai-visibility-competitors-gap-prompts:
495495
- *engineParam
496496
- *limitParam
497497
- *offsetParam
498-
- name: gap_kinds
498+
- name: gapKinds
499499
in: query
500500
required: false
501501
description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
502502
schema:
503503
type: string
504504
example: ALL
505-
- name: prompt_tab
505+
- name: promptTab
506506
in: query
507507
required: false
508508
description: Tab alias (`all-prompts`, `missing`, `shared`, `unique`)
@@ -512,7 +512,7 @@ ai-visibility-competitors-gap-prompts:
512512
- name: tab
513513
in: query
514514
required: false
515-
description: Alternative tab parameter (same values as `prompt_tab`)
515+
description: Alternative tab parameter (same values as `promptTab`)
516516
schema:
517517
type: string
518518
responses:
@@ -556,13 +556,13 @@ ai-visibility-prompts-responses-latest:
556556
Data from `PromptService/LastCrawledPromptByHash`.
557557
operationId: getAiVisibilityPromptsResponsesLatest
558558
parameters:
559-
- name: prompt_hash
559+
- name: promptHash
560560
in: query
561561
required: true
562562
description: Hash of the prompt to look up
563563
schema:
564564
type: string
565-
- name: serp_id
565+
- name: serpId
566566
in: query
567567
required: false
568568
description: SERP identifier for the prompt execution
@@ -671,7 +671,7 @@ ai-visibility-topics-stats:
671671
description: |
672672
Returns detailed statistics for a specific topic by ID,
673673
including brand mentions and visibility data.
674-
Data from `TopicService/BrandTopics` filtered by `topic_id`.
674+
Data from `TopicService/BrandTopics` filtered by `topicId`.
675675
operationId: getAiVisibilityTopicsStats
676676
parameters:
677677
- *domainParam
@@ -754,8 +754,8 @@ ai-visibility-topics-research-source-domains:
754754
description: |
755755
Returns source domains cited in LLM responses for a topic search query.
756756
Response is normalized to `{ data, total, offset, limit }` with rows
757-
containing `source_domain`, `sources_count`, `mentions`, `organic_traffic`,
758-
and optionally `prompt_example`.
757+
containing `sourceDomain`, `sourcesCount`, `mentions`, `organicTraffic`,
758+
and optionally `promptExample`.
759759
Data from `SourceService/SourceDomainsByTopicFTS` and `SourceDomainsByTopicFTSTotals`.
760760
operationId: getAiVisibilityTopicsResearchSourceDomains
761761
parameters:

docs/openapi/schemas.yaml

Lines changed: 58 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -8560,7 +8560,7 @@ AiVisibilityServiceUnavailable:
85608560
properties:
85618561
error:
85628562
type: string
8563-
example: ai_visibility_not_configured
8563+
example: aiVisibilityNotConfigured
85648564
message:
85658565
type: string
85668566
example: Missing AI_SEO_CLIENT_ID
@@ -8576,9 +8576,9 @@ AiVisibilityEngineBreakdown:
85768576
type: number
85778577
gemini:
85788578
type: number
8579-
google_ai_mode:
8579+
googleAiMode:
85808580
type: number
8581-
google_ai_overview:
8581+
googleAiOverview:
85828582
type: number
85838583

85848584
AiVisibilityByDateEntry:
@@ -8589,12 +8589,20 @@ AiVisibilityByDateEntry:
85898589
type: integer
85908590
month:
85918591
type: integer
8592+
day:
8593+
type: integer
8594+
aiVisibility:
8595+
type: number
85928596
mentions:
85938597
$ref: '#/AiVisibilityEngineBreakdown'
8594-
cited_pages:
8598+
citedPages:
85958599
$ref: '#/AiVisibilityEngineBreakdown'
8596-
visibility_by_engine:
8600+
visibilityByEngine:
85978601
$ref: '#/AiVisibilityEngineBreakdown'
8602+
ownedSources:
8603+
type: integer
8604+
audience:
8605+
type: integer
85988606

85998607
AiVisibilityByCountryEntry:
86008608
type: object
@@ -8606,7 +8614,7 @@ AiVisibilityByCountryEntry:
86068614
type: integer
86078615
audience:
86088616
type: integer
8609-
cited_pages:
8617+
citedPages:
86108618
type: integer
86118619

86128620
AiVisibilitySrFilters:
@@ -8636,15 +8644,25 @@ AiVisibilityBrandStats:
86368644
type: object
86378645
description: Brand visibility statistics response
86388646
properties:
8639-
by_date:
8647+
visibility:
8648+
type: number
8649+
visibilityByEngine:
8650+
$ref: '#/AiVisibilityEngineBreakdown'
8651+
audience:
8652+
type: integer
8653+
mentions:
8654+
$ref: '#/AiVisibilityEngineBreakdown'
8655+
citedPages:
8656+
$ref: '#/AiVisibilityEngineBreakdown'
8657+
byDate:
86408658
type: array
86418659
items:
86428660
$ref: '#/AiVisibilityByDateEntry'
8643-
by_country:
8661+
byCountry:
86448662
type: array
86458663
items:
86468664
$ref: '#/AiVisibilityByCountryEntry'
8647-
sr_filters:
8665+
srFilters:
86488666
$ref: '#/AiVisibilitySrFilters'
86498667
additionalProperties: true
86508668

@@ -8664,15 +8682,15 @@ AiVisibilityPaginatedResponse:
86648682
type: integer
86658683
limit:
86668684
type: integer
8667-
sr_filters:
8685+
srFilters:
86688686
$ref: '#/AiVisibilitySrFilters'
86698687
additionalProperties: true
86708688

86718689
AiVisibilityCompetitorsMetrics:
86728690
type: object
86738691
description: Competitor comparison time-series response
86748692
properties:
8675-
by_brand:
8693+
byBrand:
86768694
type: array
86778695
items:
86788696
type: object
@@ -8684,7 +8702,7 @@ AiVisibilityCompetitorsMetrics:
86848702
type: string
86858703
name:
86868704
type: string
8687-
by_date:
8705+
byDate:
86888706
type: array
86898707
items:
86908708
type: object
@@ -8704,9 +8722,9 @@ AiVisibilityCompetitorsMetrics:
87048722
type: number
87058723
audience:
87068724
type: number
8707-
owned_sources:
8725+
ownedSources:
87088726
type: number
8709-
sr_filters:
8727+
srFilters:
87108728
$ref: '#/AiVisibilitySrFilters'
87118729
additionalProperties: true
87128730

@@ -8722,19 +8740,19 @@ AiVisibilityGapPromptRow:
87228740
type: string
87238741
topic:
87248742
type: string
8725-
topic_id:
8743+
topicId:
87268744
type: string
8727-
topic_volume:
8745+
topicVolume:
87288746
type: integer
87298747
mentioned:
87308748
type: boolean
87318749
brands:
87328750
type: integer
87338751
sources:
87348752
type: integer
8735-
prompt_hash:
8753+
promptHash:
87368754
type: string
8737-
serp_id:
8755+
serpId:
87388756
type: string
87398757

87408758
AiVisibilityGapPromptsResponse:
@@ -8751,7 +8769,7 @@ AiVisibilityGapPromptsResponse:
87518769
type: integer
87528770
limit:
87538771
type: integer
8754-
sr_filters:
8772+
srFilters:
87558773
$ref: '#/AiVisibilitySrFilters'
87568774
required: [data, total, offset, limit]
87578775

@@ -8764,34 +8782,37 @@ AiVisibilityMeta:
87648782
items:
87658783
type: object
87668784
properties:
8767-
country_code:
8785+
countryCode:
87688786
type: string
87698787
description: ISO country code
8770-
name:
8771-
type: string
8772-
snapshots:
8788+
daily:
87738789
type: array
87748790
items:
8775-
type: string
8776-
description: Available snapshot dates
8777-
sr_filters:
8791+
type: object
8792+
monthly:
8793+
type: array
8794+
items:
8795+
type: object
8796+
isComingSoon:
8797+
type: boolean
8798+
srFilters:
87788799
$ref: '#/AiVisibilitySrFilters'
87798800
additionalProperties: true
87808801

87818802
AiVisibilityTopicsResearchStats:
87828803
type: object
87838804
description: Aggregate statistics for topic research
87848805
properties:
8785-
topics_total:
8806+
topicsTotal:
87868807
type: integer
87878808
description: Total number of distinct topics matching the query
8788-
brands_total:
8809+
brandsTotal:
87898810
type: integer
87908811
description: Total number of brands across matching topics
8791-
source_domains_total:
8812+
sourceDomainsTotal:
87928813
type: integer
87938814
description: Total number of source domains across matching topics
8794-
intent_breakdown:
8815+
intentBreakdown:
87958816
type: array
87968817
items:
87978818
type: object
@@ -8800,26 +8821,26 @@ AiVisibilityTopicsResearchStats:
88008821
type: string
88018822
count:
88028823
type: integer
8803-
related_topics_ai_volume:
8824+
relatedTopicsAiVolume:
88048825
type: integer
88058826
description: Aggregated AI volume for related topics
8806-
sr_filters:
8827+
srFilters:
88078828
$ref: '#/AiVisibilitySrFilters'
88088829
additionalProperties: true
88098830

88108831
AiVisibilitySourceDomainRow:
88118832
type: object
88128833
description: A source domain row in topic research
88138834
properties:
8814-
source_domain:
8835+
sourceDomain:
88158836
type: string
8816-
sources_count:
8837+
sourcesCount:
88178838
type: integer
88188839
mentions:
88198840
type: integer
8820-
organic_traffic:
8841+
organicTraffic:
88218842
type: integer
8822-
prompt_example:
8843+
promptExample:
88238844
type: string
88248845

88258846
AiVisibilitySourceDomainsResponse:
@@ -8836,6 +8857,6 @@ AiVisibilitySourceDomainsResponse:
88368857
type: integer
88378858
limit:
88388859
type: integer
8839-
sr_filters:
8860+
srFilters:
88408861
$ref: '#/AiVisibilitySrFilters'
88418862
required: [data, total, offset, limit]

0 commit comments

Comments
 (0)