API reference — PolyEmbed

Authentication

Header

Authorization: Bearer pe_<team>_<key>

Key format

pe_<team-slug>_<64-char-token>

Create keys in the dashboard

Endpoints

POST /api/v1/embed/

Generate an embedding vector for the given text.

Field	Type	Required	Values
text	string	Yes	any length
input_type	string	Yes	"document" \| "query"
model	string	No	"base-v2" \| "enhanced" Default "base-v2" (768 dims, multilingual). "enhanced" is not yet available. Subject to the Gemma Terms of Use.
shielded	boolean	No	true \| false — threat model
max_tokens	integer	No	512–4096 Max tokens to embed per request. Lower values = faster responses. Capped by your team's token budget (set in the dashboard), which is itself capped by your plan (free: 512, paid: 4,096).

Response — 200

{
  "embedding": [0.0229, 0.0319, -0.0165, ...],
  "model": "base-v2",
  "shielded": false,
  "dimensions": 768,
  "max_tokens": 4096
}

Code

Cause

200

Success

400

Missing or invalid fields

401

Invalid, revoked, or expired key

429

Rate limit exceeded

503

Enhanced model unavailable

Python SDK (recommended)

Install

pip install polyembed

Single

Batch

Shielded

Error handling

from polyembed import PolyEmbed

client = PolyEmbed(api_key="pe_<team>_<key>")

# Built-in retry (3x on 429/5xx) and 30s timeout
embedding = client.embed(
    "Quarterly revenue exceeded projections by 12%",
    input_type="document",
)
# embedding = [0.0229, 0.0319, ...]  (768 floats)

# Optional: limit tokens for faster responses (512–plan max)
embedding = client.embed(
    "Short lookup query",
    input_type="query",
    max_tokens=512,
)

# 1-100 texts per batch — one ONNX call, one cache round-trip
embeddings = client.embed_batch(
    ["text one", "text two", "text three"],
    input_type="document",
    max_tokens=1024,  # optional — cap tokens per text
)
# embeddings = [[0.02, ...], [0.03, ...], [0.01, ...]]

# Per-team encrypted — preserves similarity, cannot be reversed
embedding = client.embed(
    "Classified procurement report",
    input_type="document",
    shielded=True,
)

# Full response metadata
response = client.embed(
    "search query",
    input_type="query",
    raw=True,
)
# response.embedding, response.model, response.shielded, response.dimensions, response.max_tokens

from polyembed import (
    AuthenticationError,  # 401 — bad key
    ValidationError,      # 400 — bad params
    RateLimitError,       # 429 — retried automatically
    ServerError,          # 5xx — retried automatically
)

try:
    embedding = client.embed("hello", input_type="document")
except RateLimitError:
    # Only raised after max_retries (default 3) exhausted
    ...
except AuthenticationError:
    # Never retried — check your API key
    ...

Raw HTTP

cURL

Batch

Shielded

curl -X POST https://polyembed.com/api/v1/embed/ \
  -H "Authorization: Bearer pe_your_team_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Quarterly revenue exceeded projections by 12%",
    "input_type": "document",
    "max_tokens": 1024
  }'

# max_tokens is optional — omit to use your plan's default

curl -X POST https://polyembed.com/api/v1/embed/batch/ \
  -H "Authorization: Bearer pe_your_team_key" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["text one", "text two"],
    "input_type": "document",
    "max_tokens": 2048
  }'

curl -X POST https://polyembed.com/api/v1/embed/ \
  -H "Authorization: Bearer pe_your_team_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Classified document excerpt",
    "input_type": "document",
    "shielded": true
  }'

# Implement retry logic for 429/5xx responses in production.

Model licence

base-v2 is powered by Google's EmbeddingGemma. Gemma is provided under and subject to the Gemma Terms of Use found at ai.google.dev/gemma/terms.

By using the API you agree not to use the model, or its outputs, for any use restricted by the Gemma Terms of Use (Section 3.2) or the Gemma Prohibited Use Policy, or in violation of applicable laws and regulations. Google claims no rights in the embeddings you generate.