canonical: https://jentic.com/apis/jina.ai/jina-ai

# Jina The Jina Embedding Serving API

The Jina Embedding Serving API provides hosted access to Jina AI's family of embedding and reranking models through eight endpoints covering single-call `/v1/embeddings`, asynchronous `/v1/bulk-embeddings` jobs with downloadable result files, late-interaction `/v1/multi-vector` and `/v1/multi-embeddings` endpoints, and a `/v1/rerank` endpoint that scores candidate documents against a query. Authentication uses a Bearer API key sent in the Authorization header. The API is purpose-built for retrieval-augmented generation pipelines and supports multilingual and long-context embedding models.

## For AI agents

Generate text embeddings (single or bulk), produce multi-vector representations, and rerank candidate documents against a query through Jina AI's hosted model API.

## Scope

Does not host vector indices, run LLM completions, or store documents - use for text embedding generation and reranking only.

## Capabilities

- Generate dense embeddings for one or more text inputs in a single `/v1/embeddings` call
- Submit large embedding jobs asynchronously via `/v1/bulk-embeddings` and download the results as a file
- Produce late-interaction multi-vector representations for fine-grained retrieval via `/v1/multi-vector`
- Generate multi-embeddings for documents that need several vectors per record via `/v1/multi-embeddings`
- Rerank a list of candidate passages against a query using `/v1/rerank` for higher retrieval quality
- Track the status of asynchronous bulk jobs via `/v1/bulk-embeddings/{job_id}`
- Probe service health via the root / endpoint

## Use cases

### Retrieval-Augmented Generation Pipeline

An RAG system embeds the user's query with `/v1/embeddings`, retrieves the top-k candidates from a vector database, then sends query + candidates to `/v1/rerank` for a quality pass before passing the best passages to the LLM. Jina's reranker is purpose-trained for this last-mile step and typically lifts answer quality more than tweaking the retriever alone.

Example prompt: POST a query to `/v1/embeddings`, retrieve top-50 from the vector store, then POST {query, documents:[...top-50]} to `/v1/rerank` and use the top-5 by relevance score as LLM context.

### Bulk Corpus Indexing

Indexing millions of documents in real time is impractical with a single synchronous endpoint. The `/v1/bulk-embeddings` job accepts large input batches, runs them asynchronously, and exposes `/v1/bulk-embeddings/{job_id}` for status and `/v1/bulk-embeddings/{job_id}/download-result` for the resulting vectors. This is the right path for one-off corpus migrations or nightly index refreshes.

Example prompt: POST a CSV of 1M document texts to `/v1/bulk-embeddings`, poll `/v1/bulk-embeddings/{job_id}` every 60s until completed, then GET `/v1/bulk-embeddings/{job_id}/download-result` and ingest the vectors into the chosen store.

### Multilingual Semantic Search

Jina's multilingual embedding models map queries and documents in 30+ languages into a shared vector space, so a Spanish query can retrieve relevant English documents (and vice versa). This unlocks one global search index instead of per-language silos and is especially useful for support knowledge bases serving multinational customers.

Example prompt: POST a Spanish query to `/v1/embeddings` using a multilingual Jina model, then ANN-search a vector store containing English-embedded support articles and return the top match.

### AI Agent Integration via Jentic

An AI agent that builds search experiences uses Jentic to discover Jina operations by intent. The agent searches for 'rerank documents against a query' and Jentic returns the `/v1/rerank` operation with its expected query/documents body, so the agent calls it directly without reading API docs. The Jina Bearer key stays in your Jentic One instance.

Example prompt: Search Jentic for 'rerank candidate passages against a query', load the `/v1/rerank` schema, and execute it with a query and 20 retrieved candidates.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/embeddings` | Generate dense embeddings for input texts |
| POST | `/v1/rerank` | Rerank candidate documents against a query |
| POST | `/v1/bulk-embeddings` | Submit an asynchronous bulk embedding job |
| GET | `/v1/bulk-embeddings/{job_id}` | Check status of a bulk embedding job |
| GET | `/v1/bulk-embeddings/{job_id}/download-result` | Download results of a completed bulk job |
| POST | `/v1/multi-vector` | Generate late-interaction multi-vector embeddings |

## Key resources

- **Embeddings** — Generate dense vector embeddings for one or more inputs in a single call.
- **Bulk Embeddings** — Submit, monitor, and download asynchronous large-batch embedding jobs.
- **Rerank** — Score candidate passages against a query for retrieval reranking.
- **Multi-Vector** — Produce late-interaction multi-vector representations for fine-grained retrieval.

## Why Jentic

- **Setup:** Wiring the Jina Embedding Serving API by hand means handling its bearer key and managing synchronous and bulk embedding jobs yourself. Through Jentic you install once, import Jina from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Jina takes its text and query inputs in the request body, so scope by operation: limit the agent to the operations it needs, such as generating embeddings or reranking documents. You pick the allowed set, so it stays within embedding generation and reranking.
- **Credential handling:** Your Jina bearer key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate text embeddings' or 'rerank documents against a query', and Jentic returns the matching Jina operation with its body schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenAI API** — OpenAI exposes embeddings via `/v1/embeddings` as one of many model surfaces; Jina is dedicated to embeddings and reranking
- **Pinecone API** — Store Jina-generated vectors in Pinecone for fast nearest-neighbour retrieval

## FAQ

### What authentication does the Jina Embedding Serving API use?

A Bearer token issued from jina.ai/api-dashboard, sent as Authorization: Bearer <key>. Through Jentic the key is stored encrypted in the vault and injected at execution time so the agent never sees the raw value.

### Can I rerank a list of documents against a query with the Jina API?

Yes. POST {query, documents:[...]} to `/v1/rerank` and the response includes a relevance score per document. This is purpose-built for the final-stage reranking pass after a vector-store retrieval in an RAG pipeline.

### What are the rate limits for the Jina API?

Limits depend on the plan attached to the API key. Free-tier keys are throttled per minute and per day; paid plans offer higher concurrency. For very large batches, prefer `/v1/bulk-embeddings` over many synchronous `/v1/embeddings` calls to avoid 429s.

### How do I generate embeddings for a query through Jentic?

Run pip install jentic, search for 'generate text embeddings', then load and execute the POST `/v1/embeddings` operation with the input text array and the desired Jina model. Jentic returns the vectors directly to your agent.

### When should I use multi-vector instead of single-vector embeddings?

Use `/v1/multi-vector` or `/v1/multi-embeddings` for late-interaction retrieval (ColBERT-style) when document granularity matters more than a single dense vector can capture. Single `/v1/embeddings` is the right default for typical semantic search and RAG.

### Is the Jina API free?

Jina offers a free tier with a monthly token allotment that is enough to evaluate embeddings and rerank for prototypes. Production volume requires a paid plan; pricing is published at jina.ai.

### Can I limit what my agent is allowed to do with the Jina Embedding Serving API?

Yes. Jentic One is self-hosted, so you run it and your own rules decide which Jina operations the agent may call and which credentials it may use. Because Jina takes its text and query inputs in the request body, you scope by operation: allow only the endpoints the agent needs, such as POST `/v1/embeddings` for embedding generation or POST `/v1/rerank` for reranking documents, while excluding bulk jobs or multi-vector calls it should not touch. The allowed set you define keeps the agent within embedding generation and reranking, and your stored bearer key is injected only for those operations.