Embeddings API

This content is not available in your language yet.

Wetel’s knowledge base feature handles embedding and retrieval for you automatically. But sometimes you just want the raw vectors — to build your own vector index, run your own similarity search, or feed another RAG pipeline you already operate.

The embed query gives you direct, API-key-tier access to the same embedding model Wetel uses internally, with no session, no workflow, and no knowledge base required.

Overview

type EmbedUsageDto {
  inputTokens: Int!
  outputTokens: Int!
  costUsd: Float!
}

type EmbedResultDto {
  vectors: [[Float!]!]!
  usage: EmbedUsageDto!
}

extend type Query {
  embed(texts: [String!]!): EmbedResultDto!
}

Auth tier: API key only (X-Api-Key header) — no user JWT, no session, no sdkStart needed. This is a pure server-to-server call, meant to be made from your own backend.
Model: gemini-embedding-001, returning 768-dimensional float vectors.
Input limit: up to 100 texts per call. Sending more returns a BadRequestException — the request is rejected outright, never silently truncated.
Rate limit: 10 calls per minute per client IP (keyed by the caller’s IP, not by API key or tenant — see Rate Limiting). Batch your texts into fewer, larger calls rather than looping single-text requests.
Order guarantee: the returned vectors array is in the same order as the input texts array — one vector per input string.

Authentication

Generate an API key from your Wetel dashboard account (see Agents for how agents and API keys relate). This is the same long-lived X-Api-Key used elsewhere in the SDK — keep it in your backend, never in client-side code.

Every request also requires the x-huat-platform: customer header, as with every other Wetel API call.

Example request

curl -s -X POST https://api.wetel.dev/graphql \
  -H "content-type: application/json" \
  -H "x-huat-platform: customer" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{
    "query": "query Embed($texts: [String!]!) { embed(texts: $texts) { vectors usage { inputTokens outputTokens costUsd } } }",
    "variables": { "texts": ["hello world", "second string"] }
  }'

Example response shape:

{
  "data": {
    "embed": {
      "vectors": [
        [0.0123, -0.0456, "... 768 floats total"],
        [0.0789, 0.0011, "... 768 floats total"]
      ],
      "usage": {
        "inputTokens": 7,
        "outputTokens": 0,
        "costUsd": 0.00000105
      }
    }
  }
}

Usage and cost reporting

Every call returns a usage object summed across all texts in that call:

inputTokens — an estimate of tokens consumed.
outputTokens — always 0 for embeddings (there’s no generated text output).
costUsd — an estimate of the dollar cost of the call, based on the published per-token rate for gemini-embedding-001.

Important limitation: inputTokens and costUsd are estimates, derived from a character-length approximation of the input text, not an exact tokenizer count from the model provider. They’re accurate enough for cost tracking and budgeting at scale, but do not treat them as penny-exact billed figures. If you need exact billing reconciliation, use these numbers as a close approximation rather than a ledger-grade source of truth.

Why use this instead of Wetel’s knowledge base?

Wetel’s knowledge base feature already embeds and retrieves documents for you inside a workflow. Reach for the embed query directly when you want to:

Build and query your own vector index (Postgres/pgvector, Pinecone, or anything else) outside of Wetel.
Guarantee identical vectors between your own search index and anything Wetel embeds internally, so the two stay comparable without a separate re-embedding step.
Run embedding as a standalone building block in a pipeline that doesn’t otherwise touch Wetel’s chat/agent surface at all.

Common errors

Error	Cause
`Missing X-Api-Key header` / unauthorized	You sent a dashboard JWT instead of an API key, or omitted the header entirely. This endpoint is API-key-tier only.
`texts cannot exceed 100 entries per call`	Your `texts` array had more than 100 entries. Split into multiple calls.
`Platform is not specified!`	Missing the `x-huat-platform: customer` header.
Throttled / rate-limited	You exceeded 10 calls/minute from one client IP (limits are keyed by caller IP, not by API key). Batch texts into fewer calls.