feat(specs): add /semanticSearch/settings endpoint to Search API spec

[zacharynickerson]

Summary

Adds the NeuralSearch Semantic Settings API to the Search API spec.

• New path: GET /1/indexes/{indexName}/semanticSearch/settings
• New path: PUT /1/indexes/{indexName}/semanticSearch/settings
• New schema: SemanticSearchSettings and DynamicThreshold

Parameters

Parameter	Type	Description
neuralSearchMode	string	active, preview, or inactive
eventSources	string[]	Indices to use as event sources
neuralExpression	object	Attribute-to-weight map for vectorization
vectorModelId	string	Embedding model ID
neuralSearchPreset	string	conservative, expanded_reach, append_only, default, or custom
semanticBlendWeight	float	Blend weight for semantic results (custom preset only)
minHitsForSemantic	integer	Min keyword results before semantic kicks in (custom preset only)
enableNeuralSearchSortBy	boolean	Apply ranking/sorting settings to full result set (custom preset only)
dynamicThreshold	object	Semantic Precision filter config
usePositionalSemanticRanking	boolean	Apply geo/optional filters/custom ranking to vector results

Context

This endpoint was previously documented as a standalone guide page in algolia/docs-new. Per feedback from Kai Welke, the API reference is the right home for this — the guide page has been removed and will link to this reference once merged.

🤖 Generated with Claude Code

[algolia-api-clients-automation-bot]

✔️ Code generated!

Name	Link
🪓 Triggered by	8e59b0966e9ff90d34d1c6947c27ab98083dbb5a
🍃 Generated commit	4df7c8bf5cd004285baca617935c1609e4f85b70
🌲 Generated branch	generated/znickerson/neuralsearch-semantic-settings-api

📊 Benchmark results

Benchmarks performed on the method using a mock server, the results might not reflect the real-world performance.

Language	Req/s
javascript	2444
go	1895
php	1694
csharp	1468
python	1429
java	1126
ruby	886
swift	674
scala	23

[zacharynickerson]

Hey — flagging a CI issue here. The failing checks (csharp, go, java, php, python, ruby) are all failing on the withQueryCategorization e2e test, not on anything introduced by this PR. The same test is currently failing across unrelated PRs in the repo (including dependabot bumps), so this looks like a backend issue with the cts_e2e_query_categorization test index or the queryCategorization feature in the test environment.

Our changes (new getSemanticSearchSettings / setSemanticSearchSettings CTS tests, OpenAPI spec) are all clean — 23/33 checks pass. Happy to re-run once the underlying issue is resolved. Let me know if you need anything else to get this merged!

[Fluf22]

Sorry for the latency in reviewing your PR, @zacharynickerson
Wanted to double check a few things

[Fluf22]

I'm not sure to see this prop equivalent in the related repo
There's no top-level usePositionalSemanticRanking, but it has vectorTiebreaks (L65) and neuralHashScanRatio (L66).

Suggested change

	usePositionalSemanticRanking:
	type: boolean
	default: false
	description: |
	When `true`, vector results are ranked using Algolia's standard tie-breaking algorithm rather than cosine similarity alone.
	Enables custom ranking attributes, optional filters, and geo distance for semantic results.
	vectorTiebreaks:
	$ref: '#/VectorTiebreaks'
	neuralHashScanRatio:
	type: number
	format: float
	minimum: 0
	exclusiveMinimum: true
	maximum: 1
	description: |
	Fraction of the neural-hash vector index scanned when retrieving semantic results.
	Must be greater than `0` and at most `1`.

With another file for the VectorTiebreaks definition:

VectorTiebreaks:
  type: object
  description: Controls vector tie-breaking behavior at query time for semantic (vector) results.
  properties:
    enable:
      type: boolean
      description: Whether to apply vector tie-breaking to semantic results.
    usePositionalSemanticRanking:
      type: boolean
      default: false
      description: |
        When `true`, vector results are ranked using Algolia's standard tie-breaking algorithm rather than cosine similarity alone.
        Enables custom ranking attributes, optional filters, and geo distance for semantic results.

[Fluf22]

The API rejects only > 1, so the real inclusive max is 1.0; 0.999 is wrongly restrictive.

Suggested change

	maximum: 0.999
	maximum: 1

[Fluf22]

Since this is a float

Suggested change

	name: 1
	name: 1.0

[Fluf22]

Should we set a default?
It's not used in the API clients, but it can help for documentation