Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Jina AI

Scalekit connector
Open markdown

The Jina AI connector lets your AI agent act in each user's Jina AI account. Each user connects their own Jina AI access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 18 tools.

Tools
18
What they doRead · write · destructive
15 · 2 · 115 read2 write1 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Jina AI connection

    In AgentKit > Connections, create a Jina AI connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'jinaai'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Jina AI:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'jinaai_embedding_batches_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Jina AI credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • jinaai_deepsearch_chatAnswer a research question with Jina DeepSearch, which searches the web, reads pages and reasons over several rounds before answering.Read-only

    DeepSearch

    Answer a research question with Jina DeepSearch, which searches the web, reads pages and reasons over several rounds before answering. Returns an OpenAI-style chat completion: choices[0].message.content holds the final answer with its cited source URLs, plus usage. Use this for questions that need several searches and sources. It can take minutes; use reasoning_effort low for speed. Use jinaai_web_search for a single quick search.

    Inputs

    messagesarrayrequired
    Conversation so far, OpenAI chat format, ending with the user's question. Each message has role (user or assistant) and content. Example: [{"role": "user", "content": "What is the latest blog post from Jina AI?"}]
    bad_hostnamesarray
    Domains to exclude from sources. Example: ["spam-site.example"]
    boost_hostnamesarray
    Domains to prefer when reading sources. Example: ["jina.ai"]
    budget_tokensinteger
    Maximum tokens the whole research process may use; overrides reasoning_effort. Example: 200000
    max_attemptsinteger
    Maximum attempts at solving the question with different strategies; overrides reasoning_effort. Example: 1
    max_returned_urlsinteger
    Maximum number of source URLs in the final answer. Example: 5
    modelstring
    DeepSearch model (default jina-deepsearch-v1). Example: jina-deepsearch-v1default jina-deepsearch-v1
    no_direct_answerboolean
    Set true to force further search and reasoning steps even when the question looks trivial.
    only_hostnamesarray
    Only read sources from these domains. Example: ["arxiv.org"]
    reasoning_effortstring
    How hard DeepSearch works: low, medium (default) or high. Lower is faster and cheaper. Example: lowone of lowmediumhigh
    response_formatobject
    Structured output: {"type": "json_schema", "json_schema": <JSON schema>} makes the final answer match that schema. Example: {"type": "json_schema", "json_schema": {"type": "object", "properties": {"year": {"type": "number"}}}}
  • jinaai_document_transcribeTranscribe one document page image to text or markdown with Jina's jina-ocr-v1 model, or extract fields into a JSON schema.Read-only

    Transcribe Document Image

    Transcribe one document page image to text or markdown with Jina's jina-ocr-v1 model, or extract fields into a JSON schema. Returns an OpenAI-style chat completion; choices[0].message.content holds the transcription, plus usage. Use this for a scanned page or photo you have as an image. Use jinaai_url_read with respond_with jina-ocr-v1 for a page or PDF at a URL.

    Inputs

    image_urlstringrequired
    Page image to transcribe: a public image URL or a data URL (data:image/png;base64,...). Example: https://example.com/invoice-page-1.png
    max_completion_tokensinteger
    Maximum tokens in the transcription. Example: 4096
    promptstring
    Optional instruction sent with the image. Example: Transcribe this page as markdown.
    response_formatobject
    Optional structured output: {"type": "json_schema", "json_schema": {"name": "invoice", "schema": <JSON schema>}} returns the transcription as JSON matching the schema. Example: {"type": "json_schema", "json_schema": {"name": "invoice", "schema": {"type": "object", "properties": {"total": {"type": "string"}}}}}
  • jinaai_documents_rerankOrder a list of documents by how relevant each one is to a query, with a Jina reranker model.Read-only

    Rerank Documents

    Order a list of documents by how relevant each one is to a query, with a Jina reranker model. Returns results sorted by relevance, each with index (position in your list), relevance_score and, by default, the document; plus usage.total_tokens. Use this to refine search results or RAG chunks. Use jinaai_web_search to get candidates from the web first.

    Inputs

    documentsarrayrequired
    Candidate documents to rank. Each is a string, or an object such as {"text": "..."} or, for jina-reranker-m0, {"image": "<image URL or base64>"}. Example: ["Organic skincare for sensitive skin with aloe vera", "New makeup trends focus on bold colors"]
    modelstringrequired
    Reranker model. jina-reranker-v3.5 is the newest multilingual text reranker; jina-reranker-m0 also ranks images. Example: jina-reranker-v3.5one of jina-reranker-v3.5jina-reranker-v3jina-reranker-m0jina-reranker-v2-base-multilingualjina-colbert-v2
    querystringrequired
    Query to rank the documents against. Example: Organic skincare products for sensitive skin
    return_documentsboolean
    Whether each result includes the document text (default true). Set false to get only index and relevance_score.
    top_ninteger
    Number of top documents to return. Leave empty to return all of them, ranked. Example: 3
  • jinaai_embedding_batch_errors_getDownload the error lines of a Jina embedding batch job.Read-only

    Get Embedding Batch Errors

    Download the error lines of a Jina embedding batch job. Returns JSONL text, one line per input line that failed, with its error. Use this when jinaai_embedding_batch_get shows stats.failed above 0.

    Inputs

    batch_idstringrequired
    ID of the batch job, from jinaai_embedding_batch_create or jinaai_embedding_batches_list. Example: batch_abc123
  • jinaai_embedding_batch_getGet the status of one Jina embedding batch job.Read-only

    Get Embedding Batch

    Get the status of one Jina embedding batch job. Returns batch_id, status (pending, processing, completed, failed, expired or cancelled), stats (total, completed, failed, total_tokens), output_url, error_file_url, error and timestamps. Use this to poll a job until it completes. Use jinaai_embedding_batches_list to find job IDs.

    Inputs

    batch_idstringrequired
    ID of the batch job, from jinaai_embedding_batch_create or jinaai_embedding_batches_list. Example: batch_abc123
  • jinaai_embedding_batch_output_getDownload the results of a completed Jina embedding batch job.Read-only

    Get Embedding Batch Output

    Download the results of a completed Jina embedding batch job. Returns the output as JSONL text, one line per input with the embedding response for that line. Use this after jinaai_embedding_batch_get shows status completed. Large jobs return very large output.

    Inputs

    batch_idstringrequired
    ID of the batch job, from jinaai_embedding_batch_create or jinaai_embedding_batches_list. Example: batch_abc123
  • jinaai_embedding_batches_listList your recent Jina embedding batch jobs.Read-only

    List Embedding Batches

    List your recent Jina embedding batch jobs. Returns an array of jobs, each with batch_id, status, model, stats and timestamps. Use this to find a job's ID. Use jinaai_embedding_batch_get for one job.

    Inputs

    limitinteger
    Maximum number of jobs to return (default 20). Example: 50default 20
  • jinaai_embeddings_createTurn text, images or code into embedding vectors with a Jina embedding model.Read-only

    Create Embeddings

    Turn text, images or code into embedding vectors with a Jina embedding model. Returns data (one object per input with index and embedding), the model used, and usage.total_tokens. Use this for semantic search, clustering or similarity. For thousands of texts at once use jinaai_embedding_batch_create; to order search results use jinaai_documents_rerank.

    Inputs

    inputarrayrequired
    Items to embed, one embedding per item. Each item is a string, or an object such as {"text": "..."} or {"image": "<image URL or base64>"} for multimodal models (jina-embeddings-v4, jina-clip-v2). Example: ["Organic skincare for sensitive skin", "Bio-Hautpflege für empfindliche Haut"]
    modelstringrequired
    Embedding model. jina-embeddings-v5-text-small (1024 dimensions, 32K context) or -nano (768 dimensions) for text; jina-embeddings-v4 or jina-clip-v2 for text and images; jina-code-embeddings-1.5b or -0.5b for code. Use jinaai_models_list for the full catalogue. Example: jina-embeddings-v5-text-smallone of jina-embeddings-v5-text-smalljina-embeddings-v5-text-nanojina-embeddings-v5-omni-smalljina-embeddings-v5-omni-nanojina-embeddings-v4jina-embeddings-v3jina-clip-v2jina-clip-v1jina-code-embeddings-1.5bjina-code-embeddings-0.5bjina-colbert-v2jina-embeddings-v2-base-enjina-embeddings-v2-base-code
    dimensionsinteger
    Truncate each embedding to this many dimensions (Matryoshka), up to the model's size. Example: 256
    embedding_typestring
    Encoding of the returned embeddings: float (default), base64, binary or ubinary. Example: floatone of floatbase64binaryubinary
    late_chunkingboolean
    Set true to embed all text inputs as one sequence before splitting, so each chunk keeps the context of its neighbours (jina-embeddings-v3 and v4 only).
    normalizedboolean
    Whether embeddings are scaled to unit length (L2-normalized). Most models default to true.
    taskstring
    What the embeddings are for, so the model can optimize them: retrieval.query for search queries, retrieval.passage for the documents being searched, text-matching for similarity, classification, clustering (v5), separation (v3), code.query or code.passage (v4); code models use nl2code.query, nl2code.passage, qa.query, qa.passage and similar. Example: retrieval.passage
    truncateboolean
    Set true to cut inputs longer than the model's context instead of returning an error.