Skip to content

Embeddings ​

Not available yet

This feature is built but switched off for the first release. Requests to it return 404. The first release covers the LLM proxy and web search.

POST /v1/embeddings is OpenAI-compatible and serves OpenAI, Voyage and Cohere models:

bash
curl https://api.usefully.info/v1/embeddings \
  -H "Authorization: Bearer $USEFULLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "voyage/voyage-3.5", "input": ["first text", "second text"]}'
FieldNotes
modelAny model with type embedding in GET /v1/models
inputA string or an array of strings
dimensionsFor models that support shortened vectors
encoding_formatfloat (default) or base64; the OpenAI SDK requests base64 and decodes it for you

The response is OpenAI's list of embedding objects with usage.prompt_tokens, plus provider, the provider that served it.

Embeddings from different models aren't comparable. Store the model ID next to your vectors, and re-embed everything if you switch.

Reranking ​

POST /v1/rerank orders documents by relevance to a query, typically the step after retrieving candidates by embedding similarity.

bash
curl https://api.usefully.info/v1/rerank \
  -H "Authorization: Bearer $USEFULLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "cohere/rerank-v3.5", "query": "memory safety", "documents": ["…", "…"], "top_n": 5}'

Results are {index, relevance_score} pairs, best first (return_documents: true adds the text). Up to 1,000 documents per request. Cohere bills per search (one query over up to 100 documents); Voyage bills per token. Uses the embeddings scope.