Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.jina.ai
/v1/bulk-embeddings
Upload a file and get embeddings for each row
{
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_start_bulk_embedding_v1_bulk_embeddings_post"
}
}
},
"required": true
}
POST /v1/bulk-embeddings
/v1/bulk-embeddings/{job_id}/download-result
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| job_id | path | required | string |
POST /v1/bulk-embeddings/{job_id}/download-result
/v1/embeddings
Create embedding representations of the given input texts.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmbeddingsCreateRepresentationRequest"
}
}
},
"required": true
}
POST /v1/embeddings
/v1/multi-vector
Create multiple vector representations of the given input texts. One vector representation for each token in the input text.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/api_schemas__multi_embeddings__TextEmbeddingInput"
}
}
},
"required": true
}
POST /v1/multi-vector
/v1/rerank
Rank pairs.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextRankInput"
}
}
},
"required": true
}
POST /v1/rerank
Body_start_bulk_embedding_v1_bulk_embeddings_post
{
"type": "object",
"title": "Body_start_bulk_embedding_v1_bulk_embeddings_post",
"required": [
"file",
"model"
],
"properties": {
"file": {
"type": "string",
"title": "File",
"format": "binary"
},
"email": {
"type": "string",
"title": "Email",
"format": "email"
},
"model": {
"type": "string",
"title": "Model"
}
}
}
BulkEmbeddingJobResponse
{
"type": "object",
"title": "BulkEmbeddingJobResponse",
"example": {
"id": "000000000000000000000000",
"status": "in-progress",
"file_name": "input.csv",
"model_name": "model_1",
"used_token_count": 1000
},
"required": [
"user_id",
"model_name",
"status",
"file_name",
"_id"
],
"properties": {
"_id": {
"type": "string",
"title": " Id",
"description": "The ID of the job"
},
"error": {
"type": "string",
"title": "Error",
"description": "The error message of the job"
},
"status": {
"$ref": "#/components/schemas/BulkEmbeddingJobStatus"
},
"user_id": {
"type": "string",
"title": "User Id",
"description": "The user ID of the user who created the job"
},
"file_name": {
"type": "string",
"title": "File Name",
"description": "The name of the input file"
},
"created_at": {
"type": "string",
"title": "Created At",
"format": "date-time",
"nullable": false,
"description": "Time of creation of the job."
},
"model_name": {
"type": "string",
"title": "Model Name",
"description": "The name of the model to use"
},
"user_email": {
"type": "string",
"title": "User Email",
"format": "email",
"description": "The email of the user who created the job"
},
"completed_at": {
"type": "string",
"title": "Completed At",
"format": "date-time",
"description": "Time of completion of the job."
},
"used_token_count": {
"type": "integer",
"title": "Used Token Count",
"description": "The number of tokens used for the job"
},
"model_package_arn": {
"type": "string",
"title": "Model Package Arn",
"description": "The model package ARN"
}
},
"x-konfig-properties": {
"status": {
"description": "The status of the job"
}
}
}
BulkEmbeddingJobStatus
{
"enum": [
"waiting",
"in-progress",
"failed",
"completed"
],
"type": "string",
"title": "BulkEmbeddingJobStatus",
"description": "An enumeration."
}
ColbertModelEmbeddingsOutput
{
"type": "object",
"title": "ColbertModelEmbeddingsOutput",
"example": {
"data": [
{
"index": 0,
"object": "embeddings",
"embeddings": [
[
0.1,
0.2,
0.3
],
[
0.4,
0.5,
0.6
]
]
},
{
"index": 1,
"object": "embeddings",
"embeddings": [
[
0.6,
0.5,
0.4
],
[
0.3,
0.2,
0.1
]
]
}
],
"usage": {
"total_tokens": 15,
"prompt_tokens": 15
}
},
"required": [
"model",
"data",
"usage"
],
"properties": {
"data": {
"type": "array",
"items": {},
"title": "Data",
"description": "A list of Embedding Objects returned by the embedding service"
},
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"usage": {
"$ref": "#/components/schemas/api_schemas__embedding__Usage"
},
"object": {
"type": "string",
"title": "Object",
"default": "list"
}
},
"description": "Output of the embedding service",
"x-konfig-properties": {
"usage": {
"title": "Usage",
"description": "Total usage of the request. Sums up the usage from each individual input"
}
}
}
DownloadResultResponse
{
"type": "object",
"title": "DownloadResultResponse",
"example": {
"id": "000000000000000000000000X",
"download_url": "https://example.com"
},
"required": [
"id",
"download_url"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "The ID of the job"
},
"download_url": {
"type": "string",
"title": "Download Url",
"description": "The URL to download the result file"
}
}
}
EmbeddingsCreateRepresentationRequest
{
"anyOf": [
{
"$ref": "#/components/schemas/api_schemas__embedding__TextEmbeddingInput"
},
{
"$ref": "#/components/schemas/ImageEmbeddingInput"
}
],
"title": "Body"
}
HTTPValidationError
{
"type": "object",
"title": "HTTPValidationError",
"properties": {
"detail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail"
}
}
}
HealthModel
{
"type": "object",
"title": "HealthModel",
"properties": {},
"description": "Pydantic BaseModel for Jina health check, used as the response model in REST app."
}
ImageDoc
{
"type": "object",
"title": "ImageDoc",
"properties": {
"id": {
"type": "string",
"title": "Id",
"example": "d25b9372e32971ef9af12b91f524ad52",
"description": "The ID of the BaseDoc. This is useful for indexing in vector stores. If not set by user, it will automatically be assigned a random value"
},
"url": {
"type": "string",
"title": "Url",
"format": "uri",
"maxLength": 65536,
"minLength": 1,
"description": "URL of an image file"
},
"bytes": {
"type": "string",
"title": "Bytes",
"format": "binary",
"description": "Bytes representation of the Image."
}
},
"description": "BaseDoc is the base class for all Documents. This class should be subclassed\nto create new Document types with a specific schema.\n\nThe schema of a Document is defined by the fields of the class.\n\nExample:\n```python\nfrom docarray import BaseDoc\nfrom docarray.typing import NdArray, ImageUrl\nimport numpy as np\n\n\nclass MyDoc(BaseDoc):\n embedding: NdArray[512]\n image: ImageUrl\n\n\ndoc = MyDoc(embedding=np.zeros(512), image='https://example.com/image.jpg')\n```\n\n\nBaseDoc is a subclass of [pydantic.BaseModel](https://docs.pydantic.dev/usage/models/) and can be used in a similar way."
}
ImageEmbeddingInput
{
"type": "object",
"title": "ImageEmbeddingInput",
"example": {
"input": [
"bytes or URL"
],
"model": "clip"
},
"required": [
"model",
"input"
],
"properties": {
"input": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ImageDoc"
}
},
{
"$ref": "#/components/schemas/ImageDoc"
}
],
"title": "Input",
"description": "List of images to embed"
},
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"encoding_format": {
"anyOf": [
{
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
}
}
],
"title": "Encoding Format",
"description": "The format in which you want the embeddings to be returned.Possible value are `float`, `base64`, `binary`, `ubinary` or a list containing any of them. Defaults to `float` "
}
},
"description": "The input to the API for text embedding. OpenAI compatible"
}
ModelEmbeddingOutput
{
"type": "object",
"title": "ModelEmbeddingOutput",
"example": {
"data": [
{
"index": 0,
"object": "embedding",
"embedding": [
0.1,
0.2,
0.3
]
},
{
"index": 1,
"object": "embedding",
"embedding": [
0.3,
0.2,
0.1
]
}
],
"usage": {
"total_tokens": 15,
"prompt_tokens": 15
}
},
"required": [
"model",
"data",
"usage"
],
"properties": {
"data": {
"type": "array",
"items": {},
"title": "Data",
"description": "A list of Embedding Objects returned by the embedding service"
},
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"usage": {
"$ref": "#/components/schemas/api_schemas__embedding__Usage"
},
"object": {
"type": "string",
"title": "Object",
"default": "list"
}
},
"description": "Output of the embedding service",
"x-konfig-properties": {
"usage": {
"title": "Usage",
"description": "Total usage of the request. Sums up the usage from each individual input"
}
}
}
RankingOutput
{
"type": "object",
"title": "RankingOutput",
"example": {
"usage": {
"total_tokens": 15,
"prompt_tokens": 15
},
"results": [
{
"index": 0,
"document": {
"text": "Document to rank 1"
},
"relevance_score": 0.9
},
{
"index": 1,
"document": {
"text": "Document to rank 2"
},
"relevance_score": 0.8
}
]
},
"required": [
"model",
"results",
"usage"
],
"properties": {
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"usage": {
"$ref": "#/components/schemas/api_schemas__rank__Usage"
},
"results": {
"type": "array",
"items": {},
"title": "Results",
"description": "An ordered list of ranked documents"
}
},
"description": "Output of the embedding service",
"x-konfig-properties": {
"usage": {
"title": "Usage",
"description": "Total usage of the request."
}
}
}
TextRankInput
{
"type": "object",
"title": "TextRankInput",
"example": {
"model": "jina-reranker-v1-base-en",
"query": "Search query",
"documents": [
"Document to rank 1",
"Document to rank 2"
]
},
"required": [
"model",
"query",
"documents"
],
"properties": {
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/components/schemas/api_schemas__rank__TextDoc"
}
],
"title": "Query",
"description": "The search query"
},
"top_n": {
"type": "integer",
"title": "Top N",
"description": "The number of most relevant documents or indices to return, defaults to the length of `documents`"
},
"documents": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/api_schemas__rank__TextDoc"
}
}
],
"title": "Documents",
"description": "A list of text documents or strings to rerank. If a document is provided the text fields is required and all other fields will be preserved in the response."
},
"return_documents": {
"type": "boolean",
"title": "Return Documents",
"default": true,
"description": "If false, returns results without the doc text - the api will return a list of {index, relevance score} where index is inferred from the list passed into the request. If true, returns results with the doc text passed in - the api will return an ordered list of {index, text, relevance score} where index + text refers to the list passed into the request. Defaults to true"
}
},
"description": "The input to the API for text embedding. OpenAI compatible"
}
ValidationError
{
"type": "object",
"title": "ValidationError",
"required": [
"loc",
"msg",
"type"
],
"properties": {
"loc": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
}
}
api_schemas__embedding__TextDoc
{
"type": "object",
"title": "TextDoc",
"required": [
"text"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"example": "d25b9372e32971ef9af12b91f524ad52",
"description": "The ID of the BaseDoc. This is useful for indexing in vector stores. If not set by user, it will automatically be assigned a random value"
},
"text": {
"type": "string",
"title": "Text"
}
},
"description": "Document containing a text field"
}
api_schemas__embedding__TextEmbeddingInput
{
"type": "object",
"title": "TextEmbeddingInput",
"example": {
"input": [
"Hello, world!"
],
"model": "jina-embeddings-v2-base-en"
},
"required": [
"model",
"input"
],
"properties": {
"input": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/api_schemas__embedding__TextDoc"
}
},
{
"$ref": "#/components/schemas/api_schemas__embedding__TextDoc"
}
],
"title": "Input",
"description": "List of texts to embed"
},
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"encoding_format": {
"anyOf": [
{
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
}
}
],
"title": "Encoding Format",
"description": "The format in which you want the embeddings to be returned.Possible value are `float`, `base64`, `binary`, `ubinary` or a list containing any of them. Defaults to `float` "
}
},
"description": "The input to the API for text embedding. OpenAI compatible"
}
api_schemas__embedding__Usage
{
"type": "object",
"title": "Usage",
"required": [
"total_tokens",
"prompt_tokens"
],
"properties": {
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "The number of tokens used by all the texts in the input"
},
"prompt_tokens": {
"type": "integer",
"title": "Prompt Tokens",
"description": "Same as total_tokens"
}
}
}
api_schemas__multi_embeddings__TextEmbeddingInput
{
"type": "object",
"title": "TextEmbeddingInput",
"example": {
"input": [
"Hello, world!"
],
"model": "jina-colbert-v1-en"
},
"required": [
"model",
"input"
],
"properties": {
"input": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/api_schemas__embedding__TextDoc"
}
},
{
"$ref": "#/components/schemas/api_schemas__embedding__TextDoc"
}
],
"title": "Input",
"description": "List of texts to embed"
},
"model": {
"type": "string",
"title": "Model",
"description": "The identifier of the model.\n\nAvailable models and corresponding param size and dimension:\n- `jina-embedding-t-en-v1`,\t14m,\t312\n- `jina-embedding-s-en-v1`,\t35m,\t512 (default)\n- `jina-embedding-b-en-v1`,\t110m,\t768\n- `jina-embedding-l-en-v1`,\t330,\t1024\n\nFor more information, please checkout our [technical blog](https://arxiv.org/abs/2307.11224).\n"
},
"input_type": {
"enum": [
"query",
"document"
],
"type": "string",
"title": "Input Type",
"default": "document",
"description": "Type of the embedding to compute, query or document"
},
"encoding_format": {
"anyOf": [
{
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"float",
"base64",
"binary",
"ubinary"
],
"type": "string"
}
}
],
"title": "Encoding Format",
"description": "The format in which you want the embeddings to be returned.Possible value are `float`, `base64`, `binary`, `ubinary` or a list containing any of them. Defaults to `float` "
}
},
"description": "The input to the API for text embedding. OpenAI compatible"
}
api_schemas__rank__TextDoc
{
"type": "object",
"title": "TextDoc",
"required": [
"text"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"example": "d25b9372e32971ef9af12b91f524ad52",
"description": "The ID of the BaseDoc. This is useful for indexing in vector stores. If not set by user, it will automatically be assigned a random value"
},
"text": {
"type": "string",
"title": "Text"
}
},
"description": "Document containing a text field"
}
api_schemas__rank__Usage
{
"type": "object",
"title": "Usage",
"example": {
"total_tokens": 15,
"prompt_tokens": 15
},
"required": [
"total_tokens",
"prompt_tokens"
],
"properties": {
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "The number of tokens used by all the texts in the input"
},
"prompt_tokens": {
"type": "integer",
"title": "Prompt Tokens",
"description": "Same as total_tokens"
}
}
}