# n8n node

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

## Status

The node is published on npm and submitted to n8n for community node verification. Until n8n approves it, it does not appear in the Community Nodes catalogue or on n8n Cloud. The verified release is expected soon; in the meantime it installs on self-hosted n8n as below.

## Install

On self-hosted n8n, either 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/) and paste it into the credential's **API Key** field. Grant only the scopes needed: `read`, `write`, `search`, `delete` (only if deleting). **Base URL** defaults to `https://api.artefaktum.dev`; change only for self-hosting.

## Operations

### Artifact

| Operation | Purpose |
|---|---|
| Upload | Store a new artifact from a binary property or text/JSON. |
| Get or Upload | Return a cached artifact under an external key if fresh enough, else upload and cache it. |
| Download | Download an artifact's file into a binary property. |
| Get | Fetch one artifact by ID or external key. |
| Get Many | Search or list artifacts. |
| Update | Replace title, description, tags, metadata or expiry. |
| Delete | Delete an artifact by ID. |

### Project

| Operation | Purpose |
|---|---|
| Get Many | List the projects in your tenant; no parameters. |

**Project**'s "From List" mode lists your account's projects; every account also has slug `default`.

## Upload

| Parameter | Notes |
|---|---|
| Project | The owning project. |
| Input Data Source | Binary property, or text/JSON via expression. |
| Input Binary Field | Binary property holding the file. |
| Content | Text to store (text source). |
| File Name | Defaults to the binary or a generated name. |
| Content Type | Defaults to the binary type, or `text/plain`. |
| Title | Searched by agents; defaults to the file name. |
| Options → Description | Searched semantically. |
| Options → Expires In (Hours) | Auto-delete after N hours; `0` keeps it. |
| Options → External Key | Your own unique key within the project. |
| Options → Metadata (JSON) | Filterable structured metadata. |
| Options → Tags | Comma-separated. |

Node versions up to 0.1.3 still show an Options → Summary field. Leave it empty: the API refuses an upload that sets it. Version 0.2.0 removes the field.

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; Get Many only finds it once `ready`.

## Get or Upload

Same fields as Upload, plus:

| Parameter | Notes |
|---|---|
| External Key | A fresh-enough artifact with this key is returned instead of uploading. |
| Max Age (Seconds) | Reuse only if younger; `0` accepts any age. |

Output carries `cache: "hit"` or `cache: "created"`.

## Download

| Parameter | Notes |
|---|---|
| Artifact ID | E.g. from an earlier Artefaktum node. |
| Download Options → File Name | Override the output name. |
| Download Options → Put Output File in Field | Target binary property. |
| Download Options → Verify Checksum | Compare bytes to the stored SHA-256. |
| Download Options → Version ID | Defaults to latest. |

## Get

| Parameter | Notes |
|---|---|
| Lookup | By ID or by External Key. |
| Artifact ID | Lookup = By ID. |
| External Key | Lookup = By External Key. |
| Project | Resolves the key (Lookup = By External Key). |
| Simplify | Simplified vs. raw response; on by default. |

## Get Many

| Parameter | Notes |
|---|---|
| Project | Project to search or list within. |
| Query | Free text; empty lists by filters. |
| Search Mode | Hybrid, Semantic or Text. |
| Return All | Vs. a fixed Limit. |
| Limit | Max results. |
| Simplify | Simplified vs. raw response; on by default. |
| 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. |

No sort option: the API ranks results itself.

## Update

| Parameter | Notes |
|---|---|
| Artifact ID | The artifact to update. |
| 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 **Artifact ID** only.

## Recipe: caching a third-party API response

**Get or Upload** de-duplicates an expensive call (an HTTP request, an LLM generation, a report render) by keying its result so later runs, here or elsewhere, reuse it.

Give it an **External Key** such as `weather:vilnius:2026-09-23` and a **Max Age (Seconds)**. A fresh-enough artifact under that key returns as-is (`cache: "hit"`); otherwise your content uploads and is stored under it (`cache: "created"`). The key isn't workflow-scoped, so another workflow using it gets the cache too.

A worked example, Manual Trigger → HTTP Request → Get or Upload caching an hour under a per-day key, ships as [`examples/cache-api-response.json`](https://github.com/artefaktum-dev/n8n-nodes-artefaktum/blob/main/examples/cache-api-response.json) in the repo.

Get or Upload always needs the content on hand, since the API requires `size_bytes`. To skip that, call **Get** by external key first and branch on success.

## 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).