Skip to main content

Voyage AI

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

:::caution Route-specific governance The current /v1/embeddings handler authenticates the client, resolves the agent and provider, performs connected billing when enabled, and proxies the embedding request. It does not execute the Chat Completions/Responses policy chain. In particular, adding prompt-injection, PII, or audit policies to the pack does not make those policies run on embedding input. Use this integration only when that boundary is acceptable, and validate required controls outside this route before production rollout. :::

Use this page when​

  • You already have access to Voyage AI and need to route it through Keeptrusts.
  • You want one explicit provider target that can be linted and reviewed before rollout.
  • You need a stable integration contract without copying mutable prices, context limits, or retirement dates into your config.

Prerequisites​

  • Install the kt CLI.
  • Obtain the upstream credential and an enabled model or endpoint from Voyage AI.
  • Obtain a Keeptrusts runtime API token for the gateway and a separate gateway key, access key, or personal API token for client requests. --agent uses only the runtime token.

Configure the provider​

Replace the replace-with-... values before starting the gateway. The example uses the required voyage:embedding:<model> provider shorthand so 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: KEEPTRUSTS_VOYAGE_API_KEY

The public config contract requires a non-empty policies.chain. audit-logger keeps this pack valid for request families that do execute the policy pipeline; it does not add policy coverage to /v1/embeddings. The provider credential is resolved inside the gateway process; it is not the credential that client applications send to Keeptrusts.

Start and verify​

export KEEPTRUSTS_API_TOKEN="replace-with-keeptrusts-api-token"
export KEEPTRUSTS_VOYAGE_API_KEY="replace-with-upstream-credential"

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

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

In another terminal, export the separate client token, confirm the gateway is healthy, and send one request:

export KEEPTRUSTS_CLIENT_TOKEN="replace-with-separate-client-token"

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

Use the same model identifier in the request and target unless you have configured an explicit multi-model route.

Current Keeptrusts contract​

SettingBehavior
providervoyage:embedding:<model>
Upstream requestVoyage embeddings at /v1/embeddings
Upstream authenticationBearer token from KEEPTRUSTS_VOYAGE_API_KEY
Client endpoint/v1/embeddings on the Keeptrusts gateway
Policy-chain coverageThe current embeddings handler does not evaluate the Chat Completions/Responses policy chain

Embedding dimensions and accepted input options vary by model. Verify them in Voyage documentation and keep indexing and query workloads on compatible settings.

Model and production checks​

  • Verify the model ID, region, endpoint availability, and account permissions in the official provider surface before rollout.
  • Treat pricing, max_context_tokens, retention metadata, and certifications as operator declarations. Add them only after checking your current 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 every 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 server-side. Bind production listeners only to the intended interface and protect them with your normal ingress controls.

Next steps​