index4ai

n8n community node for index4.ai: ingest documents and search them for RAG and AI agents

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.2
Author: POMA AI

Documentation

@poma-ai/n8n-nodes-index4ai

An n8n community node for index4.ai, the hosted retrieval layer from POMA AI. Ingest documents, and let workflows and AI Agents search them with hybrid retrieval that returns prompt-ready context.

Installation

Follow the installation guide in the n8n docs. The package name is @poma-ai/n8n-nodes-index4ai.

Credentials

Create an API key at console.index4.ai, then add an index4.ai API credential in n8n:

Key kind API Key Project ID
Project key (poma_proj_…), bound to one project the key leave empty
Account key, can address any of your projects the key the project to use, or empty for the account's default index4.ai project

The node sends the key as a Bearer token and, when Project ID is set, an X-Project-ID header. The credential test lists one document (GET /docs?limit=1). What it tells you:

  • An unknown or expired key: "The API key was rejected".
  • A key for another POMA product (PrimeCut), or an account key with a Project ID it cannot use: "Refused: the key is for another POMA product, or the Project ID is not a project this key can use".
  • A project key with a Project ID set passes the test even when the ID is another project's; the first operation then fails with "The 'Project ID' in the credential does not match the project key's project". Leave Project ID empty with a project key.
  • Protected projects reject account keys by design, so use a project key there.

Operations

Resource Operation What it does
Document Ingest Upload a file (binary field) or a URL. index4.ai converts, chunks and indexes it. By default the node waits until the document is searchable and returns jobId, docId, status, deduplicated. With waiting off it returns the jobId right away.
Document Get Metadata of one document.
Document Get Many List the project's documents, with Return All or a Limit.
Document Delete Delete a document. Returns { "deleted": true }.
Search Search Hybrid search across the project. Prompt-Ready Text returns one item with a context block; Structured Results returns one item per matching document.
Search Search in Document The same, restricted to one document.
Job Get Status State of an ingest job started with waiting off.

Get, Get Many and Structured Results carry an Output setting: Simplified (the most useful fields), Raw (everything), or Selected Fields.

Ingest behaviour

  • Input items are all submitted first, then the node waits for the jobs together under one deadline (Timeout (Seconds), default 600, taken from the first ingest item).
  • When the project is at its concurrent job limit the API answers 429; the node waits the suggested Retry-After and retries within the deadline.
  • done, failed and blocked are final states. A job that is still running at the deadline fails with its job ID in the message, so it can be checked later with Job > Get Status. With "Continue on fail" the item carries { error, jobId, status: "timeout" }.
  • Attributes are typed, permanent names stored with the document (a JSON object such as {"region": "emea", "revision": 12}). Names must match ^[a-z0-9_]{1,64}$.
  • Attribute Filters at search time are a JSON array of clauses, for example [{"attr": "region", "op": "eq", "value": "emea"}]. Clauses combine with AND.
  • Structured Results with no matching document produce no output item; Prompt-Ready Text always returns one item.

Example workflows

Importable workflows live in examples/. In n8n, open a workflow, choose Import from File from the menu, pick the JSON file, then add your credential to the index4.ai nodes.

File What it shows
ingest-url-then-search.json Ingest a document by URL, wait for indexing, then Search in Document using the returned docId
ingest-binary-file.json Download a file with HTTP Request and ingest it from the binary field, with an attribute set
agent-with-search-tool.json Chat Trigger → AI Agent with index4.ai attached as a tool; the model fills the Query via $fromAI

Other shapes that work the same way: Google Drive Trigger → Google Drive download → Ingest from binary; Schedule Trigger → Get Many → Filter on ingested_at → Delete.

Using the node as an AI Agent tool

The node declares usableAsTool, so on n8n versions that list verified community nodes in the tool picker you can attach index4.ai to an AI Agent. Use the Search resource; leave the Query field for the model to fill. Prompt-Ready Text is the right Result Format for agents: the model receives one rendered context block with document wrappers and citation URLs.

Operations that need binary input (Ingest from a file) or that destroy data (Delete) are not meant for agent use.

Compatibility

Tested on n8n 2.44 (the n8nio/n8n image). Built against n8n-workflow 2.44 on Node 22, with no runtime dependencies.

Development

fnm use            # Node 22, from .node-version
npm install
npm run lint
npm run build
npm run dev        # n8n in Docker with this node loaded, http://localhost:5678

Use the pinned Node version: the CLI's native dependency does not build on Node 25.

docker compose up starts a plain n8n container at http://localhost:5678 with the built dist/ mounted as a custom extension, the way a self-hosted instance loads the package.

Release

A version tag triggers .github/workflows/publish.yml, which builds the package and publishes it to npm with a provenance statement. npm run release lints, builds, bumps the version, tags and pushes.

Resources

License

MIT

Discussion