n8n node

Use the Artefaktum community node in n8n to upload, cache, find and manage artifacts

This page describes node version 0.3.0. It has five operations (Upload, Get, Search, Update, Delete), one optional Key on Upload, and a Project that is already filled in. Workflows saved with 0.2.0 must be rebuilt, see What changed.

Install

The node is verified by n8n (listing), so it installs on n8n Cloud and self-hosted n8n alike. In the editor, click + to open the Nodes panel, search for Artefaktum, pick the version with the verified badge and install it. Verified nodes need an instance owner to install them once; after that everyone on the instance can use them.

On self-hosted n8n you can also install it by package name under Settings → Community Nodes, or:

npm install n8n-nodes-artefaktum

This adds node Artefaktum and credential Artefaktum API.

Credentials

Mint a key in the console and paste it into the credential’s API Key field. Grant only the scopes needed: read, write, search, delete (only if deleting). Update and Delete read the artifact first, so their key needs read as well as write or delete. Base URL defaults to https://api.artefaktum.dev; change only for self-hosting.

Operations

Operation is the first field; there is no resource picker.

Operation Purpose
Upload Store a file or text as a new artifact, or as a new version of the artifact under a key.
Get Fetch one artifact: its details, its file, or its text.
Search Find artifacts by meaning, keywords, tags and filters.
Update Change title, description, tags, metadata or expiry.
Delete Delete an artifact.

The Project field’s “From List” mode lists your account’s projects; every account also has slug default, which is the default.

Lookup: by ID or by Key

Get, Update and Delete share one lookup block.

Parameter Notes
Lookup By ID (default) or By Key.
Artifact ID Lookup = By ID.
Key Lookup = By Key.
Project Resolves the key (By Key).
Max Age (Seconds) Get only, By Key: an artifact last updated longer ago than this counts as not found. 0 accepts any age.
If Not Found Get only, By Key: Stop With Error (default) or Return found: false.

On Update and Delete a missing artifact is always an error.

Upload

Parameter Notes
Project The owning project. Defaults to default.
Input Data Source Binary File or Text.
Input Binary Field Binary property holding the file.
Content Text to store (text source).
Title Searched by agents; defaults to the file name.
Key Optional. Your own unique key within the project, e.g. report:sales:2026-10-24 or a URL.
If Key Exists Shown once Key is set: Stop With Error (default), Add New Version, or Reuse Existing.
Max Age (Seconds) With Reuse Existing: reuse only if younger. 0 accepts any age.
Options → Description Searched semantically.
Options → Tags Comma-separated.
Options → Metadata (JSON) Filterable structured metadata.
Options → Expires In (Hours) Auto-delete after N hours; 0 keeps it.
Options → File Name Defaults to the binary name, or a generated name.
Options → Content Type Defaults to the binary type, or text/plain.

Without a Key, or with Stop With Error, Upload creates a new artifact and fails if the key is taken. Add New Version stores the file as a new version of the artifact under that key (creating it if there is none), so the key always points at the latest. Reuse Existing returns the stored artifact without uploading when one exists under the key and is fresh enough (cache: "hit"); otherwise it uploads and returns the new one (cache: "created").

Field sizes are limited; see Limits.

Upload returns the artifact with status: "processing" for a few seconds while search metadata is derived; Search only finds it once ready.

Get

Parameter Notes
Lookup block See above.
Output Binary File (default), Text, or Details Only. Choose Text when an AI agent needs to read the file: agents cannot see binary files.
Options → Put Output File in Field Target binary property (Binary File).
Options → File Name Override the output name (Binary File).
Options → Max Characters Cut the content after this many characters (Text; default 50,000; 0 returns everything).
Options → Verify Checksum Compare bytes to the stored SHA-256 (Binary File, Text).
Options → Version ID Defaults to latest.
Options → Simplify Simplified vs. raw response; on by default, in every output mode.

Text reads files of at most 25 MB and refuses larger or non-text ones before downloading anything. Output adds:

  • By Key lookup: found: true.
  • A miss (or too old) with Return found: false: { "found": false, "key": ..., "project_id": ..., "reason": ... } and no binary file.
  • Text: content, content_truncated, content_characters and content_version_id, the version actually read.
Parameter Notes
Project Project to search. Defaults to default.
Query Free text; empty lists by filters.
Return All Vs. a fixed Limit.
Limit Max results.
Filters → Content Types Comma-separated MIME types.
Filters → Created After / Before Date range.
Filters → Include Superseded Include superseded artifacts.
Filters → Tags (All Of) Comma-separated; every tag must match.
Options → Search Mode Hybrid (default), Semantic or Text.
Options → Simplify Simplified vs. raw response; on by default.

No sort option: the API ranks results itself.

Update

Parameter Notes
Lookup block Find the artifact By ID or By Key.
Update Fields → Title, Description, Tags, Metadata (JSON) Leave blank to keep unchanged; clearing back to empty isn’t supported yet.
Update Fields → Expires At Set a new expiry.
Update Fields → Clear Expiry Remove the expiry.

Delete

Takes the lookup block only (By ID or By Key).

Patterns

Three chains cover most uses. None needs an error-handling trick.

Stop paying twice for the same API call. Skip the step when today’s result is already stored. Manual Trigger → Get (Lookup = By Key, Key weather:vilnius:2026-10-24, Max Age 3600, If Not Found = Return found: false, Output = Text) → IF found → true: use content; false: the expensive step (an HTTP Request, an LLM call) → Upload (same Key, If Key Exists = Add New Version). Add New Version matters because a stale copy still holds the key: the new result becomes its latest version instead of failing as a duplicate. The key isn’t workflow-scoped, so other workflows using it share the cache. A worked example ships as examples/templates/cache-expensive-step.json in the repo.

Share a file between two workflows. Build report → Upload (Key report:sales, If Key Exists = Add New Version). Consumers read it with Get (Lookup = By Key, Key report:sales).

Skip items you’ve already processed. Upload (Key = the item’s URL, If Key Exists = Reuse Existing) → IF cache equals created → do the work.

Letting an AI agent read an artifact

n8n does not pass binary files to AI agents, so a Get with the default output shows the agent only metadata. Give the agent two Artefaktum tools: Search (let the model fill Query) and Get with Output = Text (let the model fill Artifact ID from the results). Only UTF-8 text is decoded, and long files are cut at Max Characters, which keeps a large file out of the model’s context.

What changed in 0.3.0

  • The Resource picker and Project → Get Many are gone (the Project field’s From List still lists projects).
  • Get or Upload is now Upload with If Key Exists = Reuse Existing.
  • Download is now Get with Output = Binary File or Text. Get’s default Output is Binary File; use Details Only for the old behaviour.
  • Get Many is now Search. External Key is now Key. File Name and Content Type moved into Upload Options, Search Mode into Search Options.
  • Simplify moved into Options and also applies to the JSON half of Binary File and Text output.

Limits

Per-plan quotas apply (storage, rate, artifact count; see pricing), plus a per-file limit: 100 MB on Free, 5 GB on Pro. An exceeded quota returns quota_exceeded.

The node’s memory use is the tighter constraint on small instances: it buffers each file fully, roughly 2-3x its size per item. Keep files to tens of MB and avoid large batches under limited memory.

Compatibility

Requires n8n 1.0+. Tested against n8nio/n8n:latest (September 2026) and Node.js 20, 22, 24. No runtime dependencies.

See also the TypeScript SDK, the REST API, and the full README.

This page as Markdown: /docs/n8n.md