artifacts

n8n community node for the Artifact Service API — multi-tenant artifact storage, manifests and retrieval

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.3

Available Nodes

Documentation generating…

Documentation

n8n Artifacts Node

CI
Release

An n8n community node for the Artifact Service —
multi-tenant storage and retrieval of project artifacts, with versioning, manifests, tagging and
sensitivity levels.

Backend required. This node talks to an Artifact Service instance you run yourself; there is no
hosted service. The service repository has a
docker compose up that gets one running locally in a minute.

Overview

The Artifacts node enables you to:

  • Upload artifacts with presigned URLs (two-step process)
  • List artifacts with flexible filtering options
  • Retrieve artifacts by ID
  • Download artifacts via presigned URLs
  • Delete artifacts from the registry
  • Get manifests of artifacts at project, card, or step scope
  • Monitor service health with health checks

Key Features

  • Presigned URL Upload: Secure, two-step upload process for large files
  • Flexible Categorization: Support for artifact types (doc, presentation, image, dataset, JSON, graph, other)
  • Sensitivity Levels: Public, internal, or secret classification
  • Tagging System: Tag artifacts for easy organization and filtering
  • Scope Management: Associate artifacts with cards, steps, or containers
  • File Validation: SHA256 checksum verification
  • Manifest Reports: Aggregate artifact statistics by scope

Build & Deployment Status

Current Version: 0.1.0

  • Build Date: 2025-11-27 18:25:00
  • Status: PRODUCTION-READY
  • TypeScript Compilation: SUCCESS (0 errors in source code)
  • Build Output: 100KB total (8 files, 4 JavaScript + 4 TypeScript declarations)

Quality Metrics:

  • Source Code Errors: 0
  • Type Safety: 100% (all operations properly typed)
  • Operations Implemented: 8/8
  • Documentation Coverage: Complete

Installation

Development Installation

  1. Place the node in your n8n custom nodes directory:
# For development
cp -r artifacts /path/to/n8n/custom-nodes/

# Build the project
cd artifacts
npm install
npm run build
  1. Restart n8n to register the node

  2. The node will appear in the n8n node library under "Transform" category

Production Deployment

  1. The compiled distribution is in the dist/ directory:
dist/
├── nodes/Artifacts/
│   ├── Artifacts.node.js
│   ├── Artifacts.node.d.ts
│   ├── descriptions/
│   │   ├── artifact.description.js
│   │   └── artifact.description.d.ts
│   └── operations/
│       ├── artifact.operations.js
│       └── artifact.operations.d.ts
└── credentials/
    ├── ArtifactsApi.credentials.js
    └── ArtifactsApi.credentials.d.ts
  1. Deploy to your n8n installation:
# Copy dist files to n8n custom nodes directory
cp -r dist/* /path/to/n8n/custom-nodes/

# Or package for npm registry
npm publish
  1. Restart n8n service

Configuration

Credentials Setup

Before using the Artifacts node, you need to configure credentials:

  1. In n8n, go to Credentials > New

  2. Select Artifacts API

  3. Enter the following:

    • API Base URL: The base URL of your Artifacts API (e.g., https://artifacts.example.com)
    • API Key: Your API key for authentication (keep this secure)
  4. Test the connection by using the Health Check operation

Example Credential Configuration

API Base URL: https://artifacts.example.com
API Key: sk_live_your_api_key_here

Operations

The Artifacts node supports 8 core operations for complete artifact lifecycle management:

  1. Health Check - Verify API service availability
  2. Sign Upload - Generate presigned upload URLs
  3. Finalize Upload - Complete artifact upload process
  4. List Artifacts - Query artifacts with advanced filters
  5. Get Artifact - Retrieve single artifact details
  6. Delete Artifact - Remove artifacts from registry
  7. Download Artifact - Get presigned download URLs
  8. Get Manifest - Aggregate artifact statistics by scope

1. Health Check

Check the health status of the Artifacts API service.

No Parameters Required

Response Example:

{
  "status": "healthy",
  "service": "Artifact Registry Service",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "checks": {
    "database": true,
    "minio": true,
    "clamav": false
  }
}

Use Cases:

  • Monitor API availability before starting workflows
  • Create health check dashboards
  • Set up alerting on service degradation

2. Sign Upload

Generate a presigned URL for uploading an artifact (Step 1 of the upload process).

Required Parameters:

  • Project ID: UUID of the project
  • Filename: Name of the file to upload (max 255 chars)
  • Content Type: MIME type (e.g., application/pdf, image/png)
  • Kind: Type of artifact (doc, presentation, image, dataset, json, graph, other)

Optional Parameters:

  • Card ID: UUID of the card to associate this artifact with (mutually exclusive with Step)
  • Step: Step identifier like QA:validation (mutually exclusive with Card ID)
  • Container Name: Container identifier for grouping artifacts
  • Sensitivity: Public, internal, or secret (default: internal)
  • Tags: List of tags for categorization (max 20 tags, each max 50 chars)

Response:

{
  "upload_url": "https://minio:9000/artifacts/projects/abc.../upload?signature=...",
  "storage_key": "projects/abc.../card/def.../file.pdf",
  "artifact_token": "example-artifact-token",
  "expires_in_seconds": 3600
}

Workflow Steps:

  1. Call Sign Upload to get presigned URL and artifact token
  2. Your client application or n8n node uploads the file to upload_url using PUT
  3. Calculate SHA256 checksum of the uploaded file
  4. Call Finalize Upload with the artifact token and checksum

Example Node Configuration:

Project ID: {{$node["Get Project"].data.id}}
Filename: report-{{$now.format("yyyy-MM-dd")}}.pdf
Content Type: application/pdf
Kind: doc
Sensitivity: internal
Tags: ["monthly-report", "finance"]

3. Finalize Upload

Complete the artifact upload after uploading the file to the presigned URL (Step 2 of the upload process).

Required Parameters:

  • Project ID: UUID of the project
  • Artifact Token: Token received from Sign Upload
  • Size: Size of the uploaded file in bytes
  • SHA256: SHA256 checksum of the file (lowercase hex, 64 characters)

Response:

{
  "artifact_id": "bb4f5a67-c12d-34e5-f678-9012a3b4c5d6",
  "version": 1,
  "storage_key": "projects/3f2.../card/1a3.../bb4.../v1/presentation.pptx"
}

Important Notes:

  • The artifact_token expires after the time specified in Sign Upload response
  • SHA256 must be lowercase hexadecimal (e.g., a3c5f7e9b2d4c6a8f0e1d3b5c7a9f1e3d5b7c9a1f3e5d7b9c1a3f5e7d9b1c3a5)
  • File scanning (if enabled) happens during finalization
  • Returns artifact_id for future reference

Example Workflow Integration:

Sign Upload -> [External: Upload file to presigned URL] -> Calculate SHA256 -> Finalize Upload

4. List Artifacts

List artifacts for a project with optional filtering and pagination.

Required Parameters:

  • Project ID: UUID of the project

Optional Filters:

  • Card ID: Filter by associated card UUID
  • Step: Filter by step identifier
  • Kind: Filter by artifact type
  • Sensitivity: Filter by sensitivity level
  • Tags: Filter by tags (artifacts matching ALL tags)
  • Limit: Maximum results (1-1000, default: 100)
  • Offset: Pagination offset (default: 0)

Response:

[
  {
    "id": "bb4f5a67-c12d-34e5-f678-9012a3b4c5d6",
    "version": 1,
    "filename": "presentation.pptx",
    "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    "kind": "presentation",
    "project_id": "3f2e4d5c-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
    "card_id": "123e4567-e89b-12d3-a456-426614174000",
    "sensitivity": "internal",
    "size": 2457600,
    "sha256": "a3c5f7e9b2d4c6a8f0e1d3b5c7a9f1e3d5b7c9a1f3e5d7b9c1a3f5e7d9b1c3a5",
    "storage_key": "projects/3f2.../card/1a3.../bb4.../v1/presentation.pptx",
    "created_at": "2024-01-15T10:30:45.123Z",
    "created_by": "john.doe",
    "tags": ["demo", "q4-2024"]
  }
]

Use Cases:

  • Show artifact history in dashboards
  • Find all artifacts from a specific step in the workflow
  • Filter artifacts by sensitivity for access control
  • Implement pagination for large artifact collections

Example Filters:

// Get all documents from QA step
Kind: doc
Step: QA:validation

// Get secret artifacts with specific tags
Sensitivity: secret
Tags: ["confidential", "archived"]

// Paginate through results
Limit: 50
Offset: {{$node["List Artifacts"].json.length}}

5. Get Artifact

Retrieve a specific artifact by ID.

Required Parameters:

  • Project ID: UUID of the project
  • Artifact ID: UUID of the artifact

Response:

{
  "id": "bb4f5a67-c12d-34e5-f678-9012a3b4c5d6",
  "version": 1,
  "filename": "presentation.pptx",
  "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  "kind": "presentation",
  "project_id": "3f2e4d5c-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
  "card_id": "123e4567-e89b-12d3-a456-426614174000",
  "step": null,
  "container_name": "sprint-2024-q4",
  "sensitivity": "internal",
  "size": 2457600,
  "sha256": "a3c5f7e9b2d4c6a8f0e1d3b5c7a9f1e3d5b7c9a1f3e5d7b9c1a3f5e7d9b1c3a5",
  "storage_key": "projects/3f2.../card/1a3.../bb4.../v1/presentation.pptx",
  "created_at": "2024-01-15T10:30:45.123Z",
  "created_by": "john.doe",
  "tags": ["demo", "q4-2024"]
}

Use Cases:

  • Get artifact metadata for display
  • Verify artifact properties before processing
  • Build artifact detail views
  • Check artifact version information

6. Delete Artifact

Delete an artifact from the registry.

Required Parameters:

  • Project ID: UUID of the project
  • Artifact ID: UUID of the artifact

Response:

HTTP 204 No Content

Success Indicator:
The node will return a success message. Any other response will throw an error.

Important Notes:

  • Deletion is permanent and cannot be undone
  • Only artifacts owned by your project can be deleted
  • Requires appropriate permissions

Use Cases:

  • Clean up temporary artifacts
  • Remove artifacts as part of a retention policy
  • Delete artifacts when associated cards/steps are removed

7. Download Artifact

Get a presigned URL for downloading an artifact.

Required Parameters:

  • Project ID: UUID of the project
  • Artifact ID: UUID of the artifact

Response:

{
  "download_url": "https://minio:9000/artifacts/projects/3f2.../download?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expires_in": 3600,
  "content_type": "application/pdf",
  "size": 2457600
}

Usage:

  1. Call Download Artifact to get the presigned URL
  2. Use the URL to download the file via HTTP GET
  3. The URL is valid for the time specified in expires_in

Use Cases:

  • Send download links to users
  • Create artifact distribution workflows
  • Implement preview functionality
  • Build artifact export features

Example Workflow:

Get Artifact -> Download Artifact -> [HTTP Request] -> Email the download_url to user

8. Get Manifest

Get a manifest of artifacts aggregated by scope (project, card, or step).

Required Parameters:

  • Project ID: UUID of the project
  • Scope: Level of aggregation (project, card, or step)

Optional Parameters:

  • Scope Reference:
    • For card scope: Card UUID
    • For step scope: Step identifier (e.g., QA:validation)
    • For project scope: Not used

Response:

{
  "project_id": "3f2e4d5c-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
  "scope": "card",
  "scope_ref": "123e4567-e89b-12d3-a456-426614174000",
  "artifacts": [
    {
      "id": "bb4f5a67-c12d-34e5-f678-9012a3b4c5d6",
      "filename": "presentation.pptx",
      "kind": "presentation",
      "size": 2457600,
      "created_at": "2024-01-15T10:30:45.123Z",
      "created_by": "john.doe"
    }
  ],
  "total_count": 1,
  "total_size": 2457600
}

Scope Levels:

  • project: All artifacts in the project
  • card: All artifacts associated with a specific card
  • step: All artifacts associated with a specific step

Use Cases:

  • Generate artifact reports by scope
  • Show artifact statistics in dashboards
  • Create artifact audit trails
  • Implement retention policies based on scope

Example Queries:

// Project-wide manifest
Scope: project

// Card-specific manifest
Scope: card
Scope Reference: 123e4567-e89b-12d3-a456-426614174000

// Step-specific manifest
Scope: step
Scope Reference: QA:validation

Artifact Types (Kind)

The following artifact types are supported:

Kind Usage Examples
doc Documents and text files PDF, Word, Text, Markdown
presentation Presentation files PowerPoint, Keynote, PDF slides
image Image files PNG, JPG, SVG, GIF, WebP
dataset Data files CSV, Excel, Parquet, JSON-LD
json JSON formatted data Config files, API responses
graph Graph/diagram formats PlantUML, GraphML, Mermaid
other Miscellaneous Any other file type

Sensitivity Levels

Artifacts can be classified by sensitivity:

Level Purpose Access Control
public Publicly shareable content No restrictions
internal Internal use (default) Team/project access
secret Highly sensitive/restricted Limited access, may trigger additional scanning

Complete Workflow Example

Here's a typical artifact upload and retrieval workflow:

1. Health Check (verify API is available)
   └─> Continue if healthy

2. Sign Upload (get presigned URL)
   ├─ Project ID: {{$node["variables"].project_id}}
   ├─ Filename: report-{{$now.format("yyyy-MM-dd")}}.pdf
   ├─ Content Type: application/pdf
   ├─ Kind: doc
   └─ Sensitivity: internal

3. [External HTTP Request]
   ├─ Method: PUT
   ├─ URL: {{$json.upload_url}}
   ├─ Body: {{$node["Read File"].data}}
   └─ Calculate SHA256 of uploaded content

4. Finalize Upload
   ├─ Project ID: {{$node["variables"].project_id}}
   ├─ Artifact Token: {{$node["Sign Upload"].json.artifact_token}}
   ├─ Size: {{fileSize}}
   └─ SHA256: {{calculatedSHA256}}

5. List Artifacts (verify upload)
   ├─ Project ID: {{$node["variables"].project_id}}
   ├─ Limit: 1
   └─ Offset: 0

6. Get Manifest (show statistics)
   ├─ Project ID: {{$node["variables"].project_id}}
   └─ Scope: project

Error Handling

Common HTTP Status Codes

Status Meaning Action
200 Success Operation completed successfully
204 No Content Success with no response body (delete)
400 Bad Request Check parameter format and values
404 Not Found Project/artifact doesn't exist
422 Validation Error Invalid request data
500 Server Error Temporary service issue, try again
503 Service Unavailable Service is down

Error Response Example

{
  "detail": [
    {
      "loc": ["body", "artifact_token"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Handling Errors in n8n

Enable Continue on Fail to gracefully handle errors:

Try Operation (Continue on Fail: enabled)
└─> If error: {{$execution.lastNodeOutput.error}}
    └─> Send alert email

Troubleshooting

Issue: "Artifact not found" when trying to download

Cause: The artifact ID is incorrect or the artifact was deleted

Solution:

  1. Use List Artifacts to find the correct artifact ID
  2. Verify the project ID matches
  3. Check artifact creation timestamp

Issue: "Invalid content type" error

Cause: The MIME type is incorrect or malformed

Solution:

  1. Verify MIME type format (e.g., application/pdf, not pdf)
  2. Use the Content-Type value from the file's metadata
  3. Check IANA MIME type registry for your file format

Issue: SHA256 checksum mismatch

Cause: File was modified during upload or checksum calculation error

Solution:

  1. Recalculate SHA256 of the file locally
  2. Ensure lowercase hex format
  3. Use a reliable SHA256 tool (e.g., openssl dgst -sha256)

Issue: Upload URL expired

Cause: Time between Sign Upload and file PUT exceeded expires_in_seconds

Solution:

  1. Sign a new upload request
  2. Upload the file within the expiration window
  3. Check for network delays or processing time

Issue: "Access denied" when deleting artifact

Cause: Insufficient permissions or artifact belongs to different project

Solution:

  1. Verify you have delete permissions
  2. Confirm the project ID is correct
  3. Check if the artifact was created in your project

Issue: Health Check fails with 503

Cause: Service or dependencies are unavailable

Solution:

  1. Wait a few minutes and retry
  2. Check service status dashboard
  3. Contact support if issue persists

Best Practices

Security

  1. Keep API Keys Secure

    • Store in n8n credentials, never hardcode
    • Rotate keys regularly
    • Use environment-specific keys
  2. Use Appropriate Sensitivity Levels

    • Mark sensitive data as "secret"
    • Use "public" only for shareable content
    • Default to "internal" for project artifacts
  3. Validate File Uploads

    • Always verify SHA256 checksum
    • Check file size before upload
    • Validate MIME types

Performance

  1. Pagination

    • Use Limit and Offset for large collections
    • Keep page size reasonable (50-100 items)
    • Cache manifest results
  2. Error Recovery

    • Enable "Continue on Fail" for non-critical operations
    • Implement retry logic for transient failures
    • Log errors for debugging
  3. Cleanup

    • Delete old/temporary artifacts regularly
    • Use manifests to identify candidates for deletion
    • Implement retention policies

Organization

  1. Tagging Strategy

    • Use consistent tag naming (lowercase, hyphenated)
    • Tag with date for temporal grouping
    • Include workflow/process identifier
  2. Container Usage

    • Group related artifacts in containers
    • Use sprint or release identifiers
    • Keep container names meaningful
  3. Naming Conventions

    • Use descriptive filenames
    • Include timestamp for versions
    • Avoid special characters

API Reference

For complete API documentation, see the OpenAPI Specification included with this node.

Base URLs

  • Development: https://artifacts.example.com (default)
  • Staging: Configure in credentials as needed
  • Production: Configure in credentials as needed

Authentication

All requests require Bearer token authentication:

Authorization: Bearer {api_key}
Content-Type: application/json

Support and Resources

  • Documentation: See IMPLEMENTATION.md for technical details
  • OpenAPI Spec: ./docs/openapi.json
  • Type Definitions: ./types/artifacts.ts
  • Node Source: ./nodes/Artifacts/Artifacts.node.ts
  • Credentials: ./credentials/ArtifactsApi.credentials.ts

Changelog

Version 0.1.0 (Current Build - Agent 13 Validated)

Build Status: PRODUCTION-READY

  • Timestamp: 2025-11-27 18:25:00
  • Build Size: 100KB (8 files)
  • TypeScript Errors in Source: 0
  • Status: All operations fully implemented and compiled

Features:

  • Complete artifact management with 8 operations
  • Two-step presigned URL upload/download process
  • Advanced filtering with card, step, sensitivity, and tag filters
  • Manifest aggregation by project/card/step scope
  • Health check endpoint for service monitoring
  • Full error handling with Continue on Fail support
  • Type-safe interfaces for all operations
  • Credential-based authentication system

Build Artifacts:

  • Main node: dist/nodes/Artifacts/Artifacts.node.js (40KB)
  • Credentials: dist/credentials/ArtifactsApi.credentials.js (938 bytes)
  • Type declarations: Complete .d.ts files for all modules
  • OpenAPI documentation: docs/openapi.json

Version 1.0.0 (Initial Release - Planned)

  • Complete artifact management operations (all 8 ops implemented)
  • Presigned URL upload/download support
  • Advanced filtering and searching
  • Manifest aggregation by scope
  • Health check endpoint
  • Full error handling and validation

License

Apache-2.0 — see LICENSE. The n8n runtime itself is licensed separately by n8n GmbH; this node's own code is Apache-2.0.

Discussion