# 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](#what-changed-in-030).

## Install

The node is verified by n8n ([listing](https://n8n.io/integrations/artefaktum/)), 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:

```sh
npm install n8n-nodes-artefaktum
```

This adds node **Artefaktum** and credential **Artefaktum API**.

## Credentials

Mint a key in the [console](/console/?ref=n8n) 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](/docs/rest/#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.

## Search

| 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`](https://github.com/artefaktum-dev/n8n-nodes-artefaktum/blob/main/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](/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](/docs/typescript/), the [REST API](/docs/rest/), and the [full README](https://github.com/artefaktum-dev/n8n-nodes-artefaktum).
