---
title: "V1 Public Embed Text"
method: POST
path: "/v1/embeddings"
tags: ["v1"]
---

# V1 Public Embed Text

`POST /v1/embeddings`

## Request

- Base URL: `https://api.scholarfeed.org` (the document declares no server; this is the origin it was published from)
- URL: `https://api.scholarfeed.org/v1/embeddings`
- Auth: HTTP bearer

Embed text using Gemini Flash embeddings (768-dim).

Returns {embedding, model, dimensionality, task_type}. Enables agent-side
HyDE composition — an agent can build a hypothetical-document embedding
then pass it back through `search_papers(anchor_embedding=...)` (v3
surface) for hybrid retrieval.

POST is used (not GET) to accommodate long text payloads (HyDE
hypothetical-document strings can be hundreds of chars).

`task_type` defaults to RETRIEVAL_DOCUMENT (matches paper-side embeddings,
the correct space for HyDE flows). Use RETRIEVAL_QUERY for query-side
semantic search.

Thin wrapper over the existing Gemini helpers in routers/papers.py — no
duplicate Gemini client setup, no new embedding logic.

Requires a free account (any tier) — see _require_account. Each call is charged
against the account's monthly quota; anonymous callers get 403 account_required.

Rate limit: 30/minute per account. Returns 502 if the upstream Gemini
service fails (timeout / API error).

## Request body

- EmbedTextRequest: Request body for the embed_text endpoint (TOOL-02). `task_type` defaults to RETRIEVAL_DOCUMENT to match the paper-side embedding space — this is the correct default for HyDE composition (an agent builds a hypothetical-document embedding then passes it back through other tools for hybrid retrieval). Use RETRIEVAL_QUERY for query-side semantic search.
  - `text` string, required: Text to embed (1-8000 chars).
  - `task_type` 'RETRIEVAL_DOCUMENT' | 'RETRIEVAL_QUERY': Embedding task type. RETRIEVAL_DOCUMENT (default) matches paper-side embeddings for HyDE flows; RETRIEVAL_QUERY matches query-side semantic search.

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/scholarfeed/apis/scholar-feed-api.md) · [All operations](https://skmtc.dev/scholarfeed/apis/scholar-feed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scholarfeed/apis/scholar-feed-api/revisions/fc3200d27505?raw)