Skip to Content
We are live but in Staging 🎉
ModelsAPI ReferenceRerank

Rerank — API Reference

Package: dodil.ignite.v1 · Service: ModelService

Score a list of documents against a query and return them ordered by relevance — the classic retrieval re-ranking step. The HTTP surface is Cohere-compatible: the path is the top-level /v1/rerank (not under /v1/ignite/), and the JSON body matches the Cohere Rerank request exactly — top_n, return_documents, and the rest stay snake_case on both HTTP and gRPC. Use the Cohere SDK directly: see Using OpenAI & Cohere SDKs and the Model Catalog.

RPCHTTPstreaming
RerankPOST /v1/rerankunary
StreamRerankPOST /v1/rerank/streamserver-stream

gRPC reaches both methods at dodil.ignite.v1.ModelService/<Method> on $IGNITE_GRPC. See Conventions → Using gRPC for grpcurl setup. Both transports use the same Cohere-native snake_case JSON body.

Rerank

Unary reranking. Returns every result (or the top top_n) sorted by relevance_score.

Request

curl -sS -X POST "https://api.dev.dodil.io/v1/rerank" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-reranker-v2",
    "query": "What is the capital of the Netherlands?",
    "documents": [
      "Amsterdam is the capital of the Netherlands.",
      "The Hague is the seat of government.",
      "Rotterdam has the largest port in Europe."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Response

{
  "model": "jina-reranker-v2",
  "results": [
    { "index": 0, "relevance_score": 0.987, "document": "Amsterdam is the capital of the Netherlands." },
    { "index": 1, "relevance_score": 0.412, "document": "The Hague is the seat of government." }
  ],
  "usage": { "total_tokens": 64 }
}

results[].index points back into the request documents array; relevance_score is in [0.0, 1.0]. When return_documents is false, document is omitted and you map results by index.

StreamRerank

Server-streaming variant. Emits each RerankResult as it is scored, in descending relevance order. The dedicated HTTP path is /v1/rerank/stream.

Request

curl -sS -N -X POST "https://api.dev.dodil.io/v1/rerank/stream" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-reranker-v2",
    "query": "What is the capital of the Netherlands?",
    "documents": [
      "Amsterdam is the capital of the Netherlands.",
      "The Hague is the seat of government.",
      "Rotterdam has the largest port in Europe."
    ],
    "return_documents": true
  }'

Response

A stream of RerankResult messages (same shape as the unary results[] entries), emitted in descending relevance_score order.

{ "index": 0, "relevance_score": 0.987, "document": "Amsterdam is the capital of the Netherlands." }
{ "index": 1, "relevance_score": 0.412, "document": "The Hague is the seat of government." }

See also

EmbeddingsTranscription