Semantic ranking
Ranks by meaning, not just keyword overlap. A query about 'resetting credentials' matches 'change your password' even without shared words.
Semantic Search
Rank a list of documents by semantic similarity to a query
You send a `query` and a `documents` array. The service embeds both, ranks documents by cosine similarity to the query, and returns the ranked results with rank, original index, text and score, plus an echoed query and total_documents. Synchronous. Note: the field name for the candidate list is `documents`, NOT `corpus`. Earlier docs were wrong.
textanalysisnlp
Overview
Features
Rank, score, original index
Each result includes its 1-based rank, original index in the documents array, the text, and the similarity score.
Query echo
The response repeats the query and total_documents — useful for logging.
Multilingual
Query and documents can be in different languages — the embedding model maps them to the same space.
Use Cases
Document retrieval
Retrieve the most relevant chunks from a document set for a user query.
FAQ matching
Match a user question to the closest FAQ entry by meaning.
Recommendation
Find similar articles, products, or entries from a query or item description.
Input / Output
Input
query: string + documents: array of strings
JSON body
Output
results[] (rank, text, score, index), query, total_documents
JSON
Specs
- Latency
- ~0.5-3 s depending on document count
- Async
- false
- Rate Limit
- Per API key
- Max Input
- Embed model dependent — typical batch size up to a few hundred documents per request
Quickstart
Prerequisites
- -A CN8 Gateway API key with text-search in allowed_services
1. Search a document list
text-searchPOST a query and a documents array. The response ranks all documents by similarity.
POST/v1/proxy/text-search
{
"query": "electric cars",
"documents": [
"Tesla makes electric vehicles",
"Bananas are yellow fruits",
"Lithium batteries power EVs"
]
}Response
{
"status": "success",
"data": {
"results": [
{ "rank": 1, "text": "Tesla makes electric vehicles", "score": 0.7204, "index": 0 },
{ "rank": 2, "text": "Lithium batteries power EVs", "score": 0.4809, "index": 2 },
{ "rank": 3, "text": "Bananas are yellow fruits", "score": 0.1051, "index": 1 }
],
"query": "electric cars",
"total_documents": 3
}
}Field name is `documents`, not `corpus`. The response also echoes the query and the total document count.
Services
View in API ReferenceSemantic Search
POSTsyncRank a list of documents by semantic similarity to a query. Embedding-based cosine ranking.
/v1/proxy/text-search
Pricing
Billed per request.
| Service | Unit | Price |
|---|---|---|
| Semantic Search | item | $0.004/request |
- -Price is per request regardless of how many documents you rank.
Guides & Tips
Important Notes (verified against the live upstream)
- -Field name is `documents` — earlier docs called it `corpus`, which the upstream rejects with 400.
- -All documents are ranked, not just the top-k. There is no `top_k` parameter on the live endpoint.
- -Truncate client-side if you only want the top N matches.
- -Cost is per request, not per document.
How it works
- -The query and every document are encoded into dense embeddings.
- -Each document embedding is compared to the query embedding by cosine similarity.
- -Results are ranked by score; rank, original index, text and score are returned.
Tips for better results
- -Keep documents focused (e.g. paragraphs, not entire articles) for more precise matching.
- -For large-scale retrieval over thousands of documents, pre-index with `text-embeddings` and store in a vector database.
- -Use this endpoint for ad-hoc ranking over modest lists per request.
FAQ
Q: How large can `documents` be?
A: Limited by gateway/upstream payload size. Designed for short to medium lists per request (a few hundred items).
Q: Can I limit to top-k?
A: Not from the request — the upstream returns all of them ranked. Slice the results array client-side.
Q: Cross-language search?
A: Yes — the multilingual embedding model maps all languages into the same space.
Related Products
Changelog
1.2 (2026-04-29)
- -Renamed request field `corpus` → `documents` to match the live upstream.
- -Added `rank`, `query` echo, and `total_documents` to documented response shape.
- -Removed `top_k` parameter from request — not exposed on the live endpoint.
1.1 (2026-02-23)
- -Aligned with semantic_search prose (now superseded).
1.0 (2026-01-26)
- -Initial catalog.