Skip to main content

Voyage AI

Connect Verdictan to Voyage AI embeddings through the local embeddings route. Applications call the local Verdictan endpoint. The gateway owns the upstream credential and provider routing.

:::caution Route-specific governance If you use this route, accept this governance boundary.

The active /v1/embeddings handler authenticates the client and resolves the agent and provider. It processes connected billing when the config enables billing.

The handler forwards the embedding request. It does not run the Chat Completions or Responses policy chain.

Policies in the pack do not examine embedding input. These policies include prompt-injection, PII, and audit policies.

Before production rollout, validate all necessary controls that are not in this route. :::

Use this page when​

  • You have access to Voyage AI and must route it through Verdictan.
  • You want one specified provider target. You can lint and review it before rollout.
  • You want a stable integration contract. You do not want mutable prices, context limits, or retirement dates in the config.

Prerequisites​

  • Install the verdictan CLI.
  • Get the upstream credential and an enabled model or endpoint from Voyage AI.
  • Get a Verdictan runtime API token for the gateway.
  • Get a different Verdictan client API token for client requests.
  • The --agent flow uses the runtime API token for agent-bound configuration.

Configure the provider​

Before you start the gateway, replace the replace-with-... values. The example uses the necessary voyage:embedding:<model> provider shorthand. The gateway selects the embeddings request family.

pack:
  name: voyage-integration
  version: 1.0.0
  enabled: true
policies:
  chain:
    - audit-logger
providers:
  targets:
    - id: voyage-primary
      provider: "voyage:embedding:replace-with-voyage-model-id"
      base_url: https://api.voyageai.com
      secret_key_ref:
        env: VERDICTAN_VOYAGE_API_KEY

The public config contract specifies a non-empty policies.chain. With audit-logger, this pack passes config validation for request families that run the policy pipeline.

It does not add policy coverage to /v1/embeddings. The gateway process resolves the provider credential.

Client applications do not send that credential to Verdictan.

Start and verify​

export VERDICTAN_API_TOKEN="replace-with-verdictan-api-token"
export VERDICTAN_VOYAGE_API_KEY="replace-with-upstream-credential"

verdictan policy lint --file policy-config.yaml
verdictan gateway run \
  --agent voyage-integration \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

VERDICTAN_API_TOKEN authenticates the gateway runtime and control-plane synchronization. Do not reuse it as the client credential.

In a different terminal, use these commands:

export VERDICTAN_CLIENT_TOKEN="replace-with-different-client-token"

curl -fsS http://127.0.0.1:41002/healthz
curl -fsS http://127.0.0.1:41002/v1/embeddings \
  -H "Authorization: Bearer ${VERDICTAN_CLIENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"model":"replace-with-voyage-model-id","input":["Govern this text."]}'

/healthz verifies process liveness only. The authenticated embeddings request verifies the client token, provider credential, model access, and request path.

If you did not configure a specified multi-model route, use the same model identifier in the request and target.

Active Verdictan contract​

SettingBehavior
providerThe provider value is voyage:embedding:<model>.
Upstream requestThe gateway sends Voyage embeddings to /v1/embeddings.
Upstream authenticationThe gateway uses a Bearer token from VERDICTAN_VOYAGE_API_KEY.
Client endpointClient applications send requests to /v1/embeddings on the Verdictan gateway.
Policy-chain coverageThe active embeddings handler does not evaluate the Chat Completions or Responses policy chain.

Embedding dimensions and accepted input options are different for each model. Verify them in Voyage documentation and keep indexing and query workloads on compatible settings.

Transport and evidence boundary​

Verdictan configuration and adapter tests verify parsing and embeddings translation. They do not verify live credentials or active model availability.

The command above exercises one buffered embeddings request. It does not establish text generation, streaming, tools, or structured output support. Verify the selected model and input shape before production use.

Model and production checks​

  • Before rollout, verify the model ID, region, endpoint availability, and account permissions in the official provider surface.
  • Add pricing, context, retention, or certification metadata only from the active provider contract.
  • Verify input type, batch-size, token, and output-dimension limits for the selected Voyage model. The gateway forwards the OpenAI-style embeddings body and does not make each vendor-specific option portable.
  • Do not infer text-generation features such as streaming, tools, or structured output from embedding-model support.
  • Keep the upstream credential on the server.
  • Bind production listeners only to the specified interface.
  • Protect non-loopback listeners with authentication, network access controls, and TLS.

Next steps​