▣ ARTIFICIAL INTELLIGENCE

Compare and Rank Text Similarity API

What it does

Text Similarity compares two pieces of text and returns a cosine similarity score between 0 and 1. Send text1 and text2 in the request body, and get both texts back along with a similarity value.

Use it when you need a fast semantic comparison instead of exact string matching. It is useful for duplicate detection, paraphrase checks, clustering short content, or measuring how closely a generated answer matches a reference sentence.

The service also includes a ranking endpoint for semantic search. Send a query string and an array of candidates, and it returns the query plus a ranked list of candidate objects ordered by score, highest first. Each ranked item includes the candidate text and its score, which makes it straightforward to surface the best match in a UI or downstream workflow.

Text Similarity is a good fit when you want lightweight text relevance scoring without building your own embedding pipeline.

▣ ENDPOINT 01 / 02

POST

Compute cosine similarity score between two texts using sentence embeddings

http://localhost:8080/dosvak/compute-text-similarity

QUICKSTARTGUIDE

Quickstart

Compare two pieces of text for similarity with a minimal JSON request.

curl -X POST "http://localhost:8080/dosvak/compute-text-similarity" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text1":"The cat sat on the mat.","text2":"A feline rested on a rug."}'

What you'll get back

Returns a JSON object with text1 and text2 string fields, plus a similarity number between 0 and 1 indicating how similar the texts are.

{
  "text1": "The cat sat on the mat.",
  "text2": "A feline rested on a rug.",
  "similarity": 0.87
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Computes a cosine similarity score between two input texts using sentence embeddings. It returns the original text1 and text2 values along with a similarity score between 0 and 1.

Request Body

Parameter	Type	Mandatory	Description
text1	String	Yes	The first text to compare.
text2	String	Yes	The second text to compare.

Response

Returns a JSON object with text1 and text2 string fields, plus a similarity number field. The similarity value is constrained to the range 0 to 1.

Parameter	Type	Mandatory	Description
text1	String	No	The first input text.
text2	String	No	The second input text.
similarity	Number	No	The cosine similarity score between the two texts, between 0 and 1.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 02

POST

Rank candidate texts by semantic similarity to a query, highest first

http://localhost:8080/dosvak/compute-text-similarity/rank

QUICKSTARTGUIDE

Quickstart

Rank a list of candidate texts by how similar they are to your query.

curl -X POST "http://localhost:8080/dosvak/compute-text-similarity/rank" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning frameworks",
    "candidates": [
      "PyTorch for deep learning",
      "Best restaurants in Paris",
      "TensorFlow tutorial",
      "Cooking pasta at home"
    ]
  }'

What you'll get back

Returns a JSON object with a query string and a ranked array. Each item in ranked is an object with text and score fields, where score is a number indicating the similarity ranking.

{
  "query": "machine learning frameworks",
  "ranked": [
    { "text": "PyTorch for deep learning", "score": 0.98 },
    { "text": "TensorFlow tutorial", "score": 0.95 }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Ranks a list of candidate texts by their semantic similarity to a query, returning the query and a ranked list of candidate objects ordered from highest to lowest similarity.

Request Body

Parameter	Type	Mandatory	Description
query	String	Yes	The text used as the similarity query.
candidates	String Array	Yes	The candidate texts to rank against the query.

Response

Returns a JSON object with a query string field and a ranked array field. Each item in ranked is an object containing a text string and a score number.

Parameter	Type	Mandatory	Description
query	String	No	The query text used for ranking.
ranked	Object Array	No	The ranked candidate results, ordered by semantic similarity. Each item includes `text` and `score`.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.