Skip to content

Embed and rerank text

Purpose

Use governed virtual models for embedding generation and reranking. Embeddings use the OpenAI-compatible /v1/embeddings shape. /v1/rerank is a Mission Control extension. These endpoints provide inference; they do not create collections, indexes or a retrieval pipeline.

Prerequisites

  • A configured deployment with operation: embedding or operation: rerank and a provider/profile supporting that operation. See Native providers.
  • The virtual model enabled in the key's Team and model.embed or model.rerank in its actual key policy.
  • An active key and available provider credentials. Cloud credentials remain at the gateway.

Procedure

  1. From any client working directory, configure the public inference URL and a key:
export MISSION_CONTROL_URL="https://gateway.example.test"
export MISSION_CONTROL_API_KEY="mck_example_not_a_real_key"
  1. Generate ordered embeddings with a configured embedding virtual model:
curl --fail-with-body "$MISSION_CONTROL_URL/v1/embeddings" \
  --header "Authorization: Bearer $MISSION_CONTROL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"knowledge","input":["First document","Second document"],"encoding_format":"float"}'

The response has object: "list", the virtual model name, one data item per input with its original index, and usage.prompt_tokens/usage.total_tokens when reported by the provider. An embedding contains finite floats; encoding_format: "base64" requests base64-encoded float32 bytes. Optional dimensions must be a positive integer supported by the selected deployment.

  1. Rerank documents with a configured reranking virtual model:
curl --fail-with-body "$MISSION_CONTROL_URL/v1/rerank" \
  --header "Authorization: Bearer $MISSION_CONTROL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"search-ranking","query":"Reset a password","documents":["Password reset instructions","Office opening hours","Account recovery options"],"top_n":2,"return_documents":true}'

Results contain original document indexes and relevance scores. return_documents: true includes the corresponding permitted document text; it defaults to false. top_n defaults to the document count and cannot exceed it.

  1. Retain the returned Trace/correlation headers. Open the authorized Trace or Observe → Requests to inspect the route, outcome and reported usage.

Supported request fields

Endpoint Fields Bounds
/v1/embeddings model, input, encoding_format, dimensions A non-empty string or 1–128 non-empty strings; each text is at most 64 KiB. Dimensions are limited to 65,536 per vector and 1,000,000 values across a batch, with consistent non-empty finite vectors. Provider limits may be lower.
/v1/rerank model, query, documents, top_n, return_documents A non-empty query and 1–200 non-empty string documents; each text is at most 64 KiB.

Token-array embedding input, arbitrary object documents, unknown fields, streaming and governed-tool loops are not supported on these endpoints. Request JSON is limited to 2 MiB. Generic OpenAI-compatible, Azure and Titan embedding response bodies are limited to 8 MiB; every adapter validates returned vector bounds and representation. Provider limits may be stricter than gateway bounds. Invalid request shapes return invalid_request; an unsupported operation/profile returns capability_unavailable before provider dispatch.

Expected result

Every call uses the same Team allowance, current key policy, applicable Organization/Team/owner/key/customer budgets and immutable configuration boundary as a generation call. Input guardrails inspect embedding inputs and reranking queries/documents before dispatch. Redacted input is what the provider receives. Output text guardrails do not classify vector values as model-generated text.

Embedding usage has input tokens and zero output tokens. When usage and an input price are available, estimated cost uses inputCostPerMillion; an output price is not required. Rerank providers may bill by queries or documents and may not report token usage. Such values remain unknown; Mission Control does not invent token counts or a token-based price. Request and concurrency limits still apply. These endpoints do not add strict spend reservations.

A Bedrock Titan batch may require multiple upstream calls. Completed subcalls can incur charges if a later item fails. Partial work is not permission to replay the entire batch through a fallback. Review the recorded outcome and usage before retrying.

Verification

  1. Confirm the virtual model is visible to the caller in GET /v1/models.
  2. Send two synthetic embedding inputs and confirm two results with indexes 0 and 1.
  3. Check that returned dimensions match the requested/supported model dimensions and that usage is input-only.
  4. Send a synthetic rerank request and confirm indexes refer to the original documents.
  5. Disable the model in the Team and verify a subsequent call is denied without reaching the provider.
  6. If model input guardrails are active, send a synthetic policy match and inspect its decision.

Failure recovery

Result Recovery
invalid_request Use the exact fields and string inputs above; reduce batch size or text length.
capability_unavailable Check the deployment's operation, profile, dimensions and provider support. Anthropic has no native embedding or rerank operation; Azure OpenAI has no native rerank operation.
operation_denied Enable the model in the correct Team or obtain the required key policy.
guardrail_input_blocked Correct the input or have an administrator review the model policy.
A provider/authentication error Review the safe decision detail and native-provider credential setup. A failure may follow billable work; do not assume retries are free.
Unknown tokens or cost Check provider reporting and configured prices. Query/document billing is not converted into guessed token costs.