feat: Add workflow execute endpoint to public API

[samir-abis]

This PR adds a new POST /workflows/:id/execute endpoint to the n8n public API, enabling programmatic workflow execution via API keys. This addresses a long-standing gap in the public API where workflows could be created, updated, activated,
and deactivated, but not executed directly by ID.

What Changed:

• API Key Permissions: Added execute operation to workflow resource permissions for API keys
• New Endpoint: Implemented POST /workflows/:id/execute that:
  • Validates API key has workflow:execute scope
  • Executes the workflow using WorkflowExecutionService.executeManually()
  • Emits workflow-pre-execute event for tracking/hooks
  • Returns execution ID and webhook wait status
• OpenAPI Documentation: Added complete OpenAPI specification for the new endpoint
• Error Handling: Proper 400/401/404/500 responses with appropriate error messages

Why This Matters:

Before this PR, users had to either:

1. Use webhook triggers (requiring workflow redesign)
2. Send the entire workflow definition with all nodes/connections to execute it
3. Use undocumented internal endpoints like /rest/workflows/run (discouraged)

After this PR, users can simply execute any workflow by ID:

curl -X POST https://your-n8n-instance.com/api/v1/workflows/{workflowId}/execute \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json"

Expected response:

{
  "executionId": 1,
  "waitingForWebhook": false
}

Use Cases:

• External systems triggering n8n workflows programmatically
• CI/CD pipelines executing workflows as part of deployment
• Integration platforms that need to trigger workflows based on events
• Automation tools managing complete workflow execution lifecycle

Related Linear tickets, Github issues, and Community forum posts

Closes #14002 - API call errors with workflow execution endpoint (reported 404 errors)

Community Forum Discussions:

• https://community.n8n.io/t/execute-a-workflow-through-api/3197 (2020)
• https://community.n8n.io/t/how-to-use-an-api-to-execute-a-workflow/29656 (2023)
• https://community.n8n.io/t/start-workflow-with-an-api-call/48797

These discussions show users have been requesting this functionality for years, with the official recommendation being to use webhooks as a workaround.

Review / Merge checklist

• PR title and summary are descriptive. (https://github.com/n8n-io/n8n/blob/master/.github/pull_request_title_conventions.md)
• https://github.com/n8n-io/n8n-docs or follow-up ticket created.
• Tests included.
• PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)

Notes for Reviewers:

• OpenAPI spec properly references existing response schemas
• Follows existing patterns in workflows.handler.ts codebase
• Uses proper scope validation (apiKeyHasScope, projectScope)
• Leverages existing WorkflowExecutionService for consistent execution behavior
• Event emission maintains compatibility with existing hooks/tracking systems

---

Note

Introduces a public API endpoint to execute a workflow by ID and grants API keys the workflow:execute scope.

• Public API
  • New Endpoint: POST /workflows/{id}/execute in workflows.handler.ts using WorkflowExecutionService.executeManually(); validates workflow:execute scope and project access; returns execution info; handles 400/401/404/500.
  • OpenAPI: Adds path in openapi.yml and spec file handlers/workflows/spec/paths/workflows.id.execute.yml documenting response shape.
• Permissions
  • Adds execute to API key workflow resource in @n8n/permissions/constants.ee.ts.
• Tests
  • Integration tests for execution endpoint: auth failures, 404 on missing workflow, success for owner/member, and 403 without permissions.

^{Written by Cursor Bugbot for commit 56dd8d0. This will update automatically on new commits. Configure here.}

[samir-abis]

from #20234

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (all 1 issues)

Understand the root cause of the following 1 issues and fix them.


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

<violation number="1" location="packages/cli/test/integration/public-api/workflows.test.ts:1644">
`execute` returns 404 with message `Workflow with ID &quot;999&quot; not found.` from the scope middleware, but the test asserts `&#39;Not Found&#39;`, so the test will fail. Please update the expectation to match the actual message returned by the endpoint.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[Joffcom]

Hey @samir-abis,

Thank you for your contribution. We appreciate the time and effort you’ve taken to submit this pull request.

Before we can proceed, please ensure the following:
• Tests are included for any new functionality, logic changes or bug fixes.
• The PR aligns with our contribution guidelines.

Regarding new nodes:
We no longer accept new nodes directly into the core codebase. Instead, we encourage contributors to follow our Community Node Submission Guide to publish nodes independently.

If your node integrates with an AI service that you own or represent, please email [email protected] and we will be happy to discuss the best approach.

About review timelines:
This PR has been added to our internal tracker as "GHC-4791". While we plan to review it, we are currently unable to provide an exact timeframe. Our goal is to begin reviews within a month, but this may change depending on team priorities. We will reach out when the review begins.

Thank you again for contributing to n8n.

[PedroKafka]

I would really appreciate it if this feature were implemented.