feat(core): Add public API endpoints for workflow archive and unarchive

[sandra0503]

Summary

• Adds POST /workflows/{id}/archive and POST /workflows/{id}/unarchive to the public API (v1)
• Archiving an already-archived workflow returns 200
• Both endpoints use the existing workflow:delete scope
• Adds publicApi flag to archive/unarchive events for telemetry attribution
• Introduces respondWithPublicApiError shared helper for consistent public API error responses

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/LIGO-384

Review / Merge checklist

• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...lic-api/v1/handlers/workflows/workflows.handler.ts	91.30%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

2 issues found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/public-api/v1/handlers/workflows/workflows.handler.ts">

<violation number="1" location="packages/cli/src/public-api/v1/handlers/workflows/workflows.handler.ts:460">
P2: Handle BadRequestError from unarchive so an already-active workflow returns a 400 instead of a server error. According to linked Linear issue LIGO-384, the public API must handle the "already active when trying to unarchive" case explicitly.</violation>
</file>

<file name="packages/cli/test/integration/public-api/workflows.test.ts">

<violation number="1" location="packages/cli/test/integration/public-api/workflows.test.ts:1249">
P2: Add 403 authorization-scope tests for archive/unarchive (API key present but missing `workflow:delete`) to cover the LIGO-384 acceptance criteria.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as API Client
    participant Handler as Public API Handler (v1)
    participant Service as Workflow Service
    participant Finder as Workflow Finder
    participant History as Workflow History Service
    participant DB as Database
    participant Events as Event Service

    Note over Client,Events: NEW: Public API Workflow Archive/Unarchive Flow

    Client->>Handler: POST /workflows/{id}/archive
    
    rect rgb(240, 240, 240)
    Note right of Handler: Auth & Middleware
    Handler->>Handler: Validate API Key Scope (workflow:delete)
    Handler->>Handler: Validate Project Scope (workflow)
    end

    Handler->>Service: NEW: archiveForPublicApi(user, id)
    Service->>Finder: findWorkflowForUser(id, user, ['workflow:delete'])
    Finder-->>Service: WorkflowEntity or undefined

    alt Workflow Not Found
        Service-->>Handler: undefined
        Handler-->>Client: 404 Not Found
    else Workflow Found
        Service->>Service: Check if already archived
        
        opt Is NOT already archived
            Service->>History: saveVersion(user, workflow)
            Service->>DB: Set isArchived = true
            Service->>Events: CHANGED: emit 'workflow-archived' (publicApi: true)
            Service->>Service: Run 'workflow.afterArchive' hooks
        end

        Service-->>Handler: WorkflowEntity
        Handler-->>Client: 200 OK (Workflow JSON)
    end

    Note over Client,Events: NEW: Unarchive Flow (similar logic)

    Client->>Handler: POST /workflows/{id}/unarchive
    Handler->>Service: NEW: unarchiveForPublicApi(user, id)
    Service->>Service: unarchive(user, id, { publicApi: true })
    
    alt Workflow is not archived
        Service-->>Handler: throw BadRequest (already active)
        Handler-->>Client: 400 Bad Request
    else Workflow is archived
        Service->>DB: Set isArchived = false
        Service->>Events: CHANGED: emit 'workflow-unarchived' (publicApi: true)
        Service-->>Handler: WorkflowEntity
        Handler-->>Client: 200 OK
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[geemanjs]

Is it a normal pattern to pass this through on events?

[ireneea]

Yeah most of the workflow-* events have that publicApi flag. The events that don't have it can't be triggered by the public api like workflow-pre-execute and workflow-post-execute

[ireneea]

Do we even want to start using this?

[sandra0503]

Agreed on Slack, no version bump needed

[ireneea]

Should we remove this empty file?

[sandra0503]

100%

[n8n-assistant]

Got released with n8n@2.15.0