{"openapi":"3.1.0","info":{"title":"n8n (BYOK) API","version":"0.1.0","description":"n8n (BYOK) lets an AI assistant read your own n8n data through the n8n API with a key you supply (n8n API key). Read-only: 8 tools (list_workflows, get_workflow, get_workflow_tags, list_executions, get_execution, list_tags, list_projects, get_insights_summary). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-n8n.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-n8n/docs"},"termsOfService":"https://connectorbay.com/byok-n8n/terms"},"servers":[{"url":"https://byok-n8n.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-n8n/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_workflows":{"post":{"operationId":"list_workflows","summary":"List the workflows of an n8n Cloud instance with name, active state, trigger count and dates (no node contents). Filter ","description":"List the workflows of an n8n Cloud instance with name, active state, trigger count and dates (no node contents). Filter by active state, name, tag or project. Page with nextCursor. Use for \"Which of my n8n workflows are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"active":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"true for only active workflows, false for only inactive.","title":"Active"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows with this name.","title":"Name"},"tags":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows with these tag names, comma separated.","title":"Tags"},"project_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows of this project id.","title":"Project Id"},"exclude_pinned_data":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":"true","description":"true (default) leaves out pinned test data, which keeps the answer small.","title":"Exclude Pinned Data"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 250; n8n's default is 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: nextCursor from the previous answer. Leave out for the first page.","title":"Cursor"}},"required":["instance"],"title":"list_workflowsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_workflow":{"post":{"operationId":"get_workflow","summary":"Get one n8n workflow by id: name, description, active state, version, trigger count, dates and timezone. Node settings a","description":"Get one n8n workflow by id: name, description, active state, version, trigger count, dates and timezone. Node settings and credentials are not returned. Use for \"Show details of my n8n workflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"workflow_id":{"description":"n8n workflow id, as returned by list_workflows.","maxLength":60,"title":"Workflow Id","type":"string"}},"required":["instance","workflow_id"],"title":"get_workflowArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_workflow_tags":{"post":{"operationId":"get_workflow_tags","summary":"List the tags attached to one n8n workflow. Use for \"Which tags does my n8n workflow have\".","description":"List the tags attached to one n8n workflow. Use for \"Which tags does my n8n workflow have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"workflow_id":{"description":"n8n workflow id, as returned by list_workflows.","maxLength":60,"title":"Workflow Id","type":"string"}},"required":["instance","workflow_id"],"title":"get_workflow_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_executions":{"post":{"operationId":"list_executions","summary":"List recent n8n executions (newest first) with workflow id, status (success, error, running, waiting, ...), mode and sta","description":"List recent n8n executions (newest first) with workflow id, status (success, error, running, waiting, ...), mode and start and stop times. Execution data is never included. Page with nextCursor. Use for \"Which n8n executions failed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"status":{"anyOf":[{"enum":["canceled","crashed","error","new","running","success","unknown","waiting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only executions with this status.","title":"Status"},"workflow_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only executions of this workflow id.","title":"Workflow Id"},"project_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only executions of this project id.","title":"Project Id"},"started_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only executions started after this ISO 8601 time.","title":"Started After"},"started_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only executions started before this ISO 8601 time.","title":"Started Before"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 250; n8n's default is 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: nextCursor from the previous answer. Leave out for the first page.","title":"Cursor"}},"required":["instance"],"title":"list_executionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_execution":{"post":{"operationId":"get_execution","summary":"Get one n8n execution by id: workflow, status, mode, start and stop times and retry information. Execution data is not i","description":"Get one n8n execution by id: workflow, status, mode, start and stop times and retry information. Execution data is not included. Use for \"Did n8n execution 1234 succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"execution_id":{"description":"n8n execution id (a number), as returned by list_executions.","minimum":1,"title":"Execution Id","type":"integer"}},"required":["instance","execution_id"],"title":"get_executionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List all tags defined in an n8n instance with id, name and dates. Page with nextCursor. Use for \"Which tags exist in my ","description":"List all tags defined in an n8n instance with id, name and dates. Page with nextCursor. Use for \"Which tags exist in my n8n instance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 250; n8n's default is 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: nextCursor from the previous answer. Leave out for the first page.","title":"Cursor"}},"required":["instance"],"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List the projects of an n8n instance with name, type (personal or team), description and dates. Page with nextCursor. Us","description":"List the projects of an n8n instance with name, type (personal or team), description and dates. Page with nextCursor. Use for \"Which projects does my n8n instance have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 250; n8n's default is 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: nextCursor from the previous answer. Leave out for the first page.","title":"Cursor"}},"required":["instance"],"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_summary":{"post":{"operationId":"get_insights_summary","summary":"Get n8n run statistics for a period: total and failed executions, failure rate, time saved and average run time, each wi","description":"Get n8n run statistics for a period: total and failed executions, failure rate, time saved and average run time, each with the change versus the previous period. Use for \"What is my n8n failure rate this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"instance":{"description":"Your n8n Cloud subdomain: the part before .app.n8n.cloud, for example 'mycompany' for mycompany.app.n8n.cloud.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Instance","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period (ISO 8601 time).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period (ISO 8601 time).","title":"End Date"},"project_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this project id.","title":"Project Id"}},"required":["instance"],"title":"get_insights_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}