JSON Schema for n8n Workflows
An n8n workflow exported as JSON is a structured object with top-level fields such as id,
name, active, nodes, connections, credentials, settings, staticData, versionId, and optional
meta data[1][2]. Key elements include:
• id (string) – the workflow’s unique identifier (often omitted when
importing).
• name (string) – a descriptive name for the workflow.
• active (boolean) – whether the workflow is active (true) or not
(false).
• nodes (array of objects) – each node object must include:
• id (unique node ID string), name (node label), type (node type
name), typeVersion (version number), and position (array of two numbers for UI
position).
• A parameters object with the node’s configuration fields.
• An optional credentials object mapping credential-type keys to
credential references (each with id and name of the credential).
• Optional disabled flag.
• connections (object) – defines links between nodes. Each key is a
source node name, mapping to objects like:
• "connections": {
"Source Node Name": {
"main": [
[
{
"node": "Target Node Name",
"type": "main",
"index": 0
}
]
]
}
}
• This indicates data flows from the source node’s “main” output into
the target node’s input[3].
• credentials (object) – a map of credential-type keys to credential
references. Each entry has a type name (e.g. githubApi, slackApi, httpBasicAuth,
etc.) and an object with the credential’s id and name. For example:
• "credentials": {
"githubApi": {
"id": "existing-credential-id",
"name": "GitHub Credential"
},
"slackApi": {
"id": "existing-slack-id",
"name": "Slack Bot"
}
}
• The id here is the internal credential ID; after import this ID may
no longer be valid and must be mapped in the target system[4].
• settings (object) – workflow-level settings (e.g. executionOrder).
• staticData (object) – optional data used internally.
• versionId (string) – the workflow’s version ID for import
compatibility.
• meta (object, optional) – metadata for imports (e.g.
templateCredsSetupCompleted, instanceId)[5].
These fields must match the n8n JSON schema. In summary: nodes, connections, name,
active, settings, staticData (and often id, versionId, and meta) are required at the root[1].
Node objects require keys like id, name, type, position, parameters, and optional
credentials and disabled. Connections specify target node names, types, and indexes[1]
[3].
Supported Credential Types (Structures and Examples)
n8n defines many credential types. Here we detail a few common ones and their expected
JSON payload when creating credentials via the API. In all cases, the JSON body must
include at least name, type, and a data object with the credential fields (and optionally
nodesAccess if assigning node-specific permissions). You can discover the exact schema
for a credential type by calling /api/v1/credentials/schema/{credentialTypeName}[6] (the
API version is 1[7]). Example payloads:
• GitHub API (githubApi) – Typically uses a personal access token.
• {
"name": "My GitHub Token",
"type": "githubApi",
"data": {
"accessToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"
}
}
• This payload creates a credential of type githubApi with the given
access token[8].
• Google OAuth2 (googleOAuth2Api) – Uses OAuth2 client
credentials and token data.
• {
"name": "My Google OAuth2",
"type": "googleOAuth2Api",
"data": {
"clientId": "[Link]",
"clientSecret": "your-client-secret",
"scope": "openid profile email",
"accessToken": "ya29.a0A...user-access-token...",
"refreshToken": "1//0gQ..."
}
}
• (Exact field names may include nested oauthTokenData for full
token details, depending on the OAuth flow[9].)
• API Key Auth (apiKeyAuth) – A simple header- or query-key
credential.
• {
"name": "My API Key",
"type": "apiKeyAuth",
"data": {
"name": "X-API-KEY",
"value": "ABCDEFGHIJ1234567890"
}
}
• Here name and value are the key header/name and its token value.
• HTTP Basic Auth (httpBasicAuth) – Username/password
credentials.
• {
"name": "My Basic Auth",
"type": "httpBasicAuth",
"data": {
"user": "myusername",
"password": "mypassword"
}
}
• Slack API (slackApi) – A Slack app or bot token.
• {
"name": "My Slack Bot",
"type": "slackApi",
"data": {
"accessToken": "xoxb-111111111111-
XXXXXXXXXXXXXXXXXXXXXXXX"
}
}
• (This uses Slack’s “Bot User OAuth Access Token” from your
app’s credentials[10].)
Each of these payloads can include "nodesAccess" if you want to restrict which nodes
may use the credential (an array of { nodeType: "[Link]" } objects).
For example:
"nodesAccess": [
{ "nodeType": "[Link]" },
{ "nodeType": "[Link]" }
]
Example Workflows
Below are two example workflow JSONs.
• With Credential Placeholders: a workflow that uses Slack and
GitHub credentials, referenced by placeholder IDs. (In practice you would replace
"CREDENTIAL_ID_*" with real IDs obtained from the API.)
{
"name": "Workflow With Credentials",
"active": false,
"nodes": [
{
"parameters": {
"url": "[Link]
"authentication": "basicAuth"
},
"credentials": {
"httpBasicAuth": {
"id": "CREDENTIAL_ID_HTTP",
"name": "My Basic Auth"
}
},
"id": "1",
"name": "Fetch Data",
"type": "[Link]",
"typeVersion": 2,
"position": [250, 300]
},
{
"parameters": {
"authentication": "oAuth2",
"text": "Data fetched: {{ $('Fetch Data').[Link] }}",
"select": "channel",
"channelId": "C1234567890"
},
"credentials": {
"slackApi": {
"id": "CREDENTIAL_ID_SLACK",
"name": "Slack Bot"
}
},
"id": "2",
"name": "Send Slack Alert",
"type": "[Link]",
"typeVersion": 1,
"position": [450, 300]
}
],
"connections": {
"Fetch Data": {
"main": [
[
{
"node": "Send Slack Alert",
"type": "main",
"index": 0
}
]
]
}
},
"credentials": {
"httpBasicAuth": {
"id": "CREDENTIAL_ID_HTTP",
"name": "My Basic Auth"
},
"slackApi": {
"id": "CREDENTIAL_ID_SLACK",
"name": "Slack Bot"
}
},
"settings": {},
"staticData": {},
"versionId": "1"
}
This example shows two nodes linked together. Each node’s credentials section refers to a
credential by id and name. (In the workflow-level credentials object you can also list
them centrally.) The connections use the source node’s name as a key[1][3].
• Without Credentials: a fully defined workflow that uses no
external credentials (all operations use built-in logic).
{
"name": "Workflow Without Credentials",
"active": true,
"nodes": [
{
"parameters": {
"values": [
{ "name": "firstName", "value": "Alice" }
]
},
"id": "1",
"name": "Set",
"type": "[Link]",
"typeVersion": 1,
"position": [250, 300]
},
{
"parameters": {
"conditions": {
"boolean": [
{
"value1": "={{ $node[\"Set\"].json[\"firstName\"] }}",
"value2": "Alice",
"operation": "equal"
}
]
}
},
"id": "2",
"name": "Check Name",
"type": "[Link]",
"typeVersion": 2,
"position": [450, 300]
}
],
"connections": {
"Set": {
"main": [
[
{
"node": "Check Name",
"type": "main",
"index": 0
}
]
]
}
},
"credentials": {},
"settings": {},
"staticData": {},
"versionId": "1"
}
This workflow simply sets a variable and checks it in an IF node. There are no
credentials used (credentials is an empty object) and all nodes are defined. The root-level
keys (nodes, connections, etc.) match the schema above[1].
n8n Cloud API Contract
Authentication: n8n Cloud uses API keys. Every request must include an X-N8N-API-
KEY header with a valid API key[11]. For example:
curl -X GET "[Link] \
-H "accept: application/json" \
-H "X-N8N-API-KEY: <your-api-key>"
This example (from the n8n docs) shows listing active workflows[12]. All API requests
require: - X-N8N-API-KEY: your-api-key - Content-Type: application/json for requests
with a body.
Available Endpoints: (base path /api/v1)
• Workflows:
• GET /workflows – List workflows (supports query parameters
like ?active=true[12]).
• GET /workflows/{id} – Retrieve a specific workflow by ID.
• POST /workflows – Create a new workflow. The JSON body is the
workflow definition.
• PUT /workflows/{id} – Update an existing workflow (full
replacement). Send the updated JSON.
• DELETE /workflows/{id} – Delete a workflow by ID.
• Credentials: (project-wide credentials)
• GET /credentials – Not supported (returns “Method Not
Allowed”[13]). Credentials cannot be listed by this endpoint.
• POST /credentials – Create a new credential. Body example:
• {
"name": "example-ssh",
"type": "sshPassword",
"data": {
"host": "[Link]",
"port": 22,
"username": "builder",
"password": "mypassword"
}
}
• On success this returns the new credential with its id (see example
in [54])[14].
• PUT /credentials/{id} – Update an existing credential (e.g. to
change its name or secret). A new API key scope credential:update is required to
use this endpoint[15]. Example request:
• curl -X PUT
"[Link] \
-H "X-N8N-API-KEY: <your-key>" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Name", "data": {"token": "new-token"}}'
• (Upon success returns the updated credential or status.)[15][16].
• DELETE /credentials/{id} – Delete a credential. On success it
typically returns a 204 No Content.
Request Headers: Every request must include the API key header. For JSON bodies, use
Content-Type: application/json. Optionally include Accept: application/json.
Response Formats: On success, workflows and credentials endpoints return JSON
objects with the created/updated data: - Create Credential (201): Returns JSON with id,
name, type, createdAt, etc. (see example[14]).
- Create/Update Workflow (200/201): Returns the workflow JSON (often with updated
id, versionId, etc.).
- List Workflows (200): Returns a JSON array of workflow objects (possibly paginated).
Error responses use standard HTTP status codes and JSON error messages. For example,
missing required fields or invalid schema returns a 400 with a message field. A sample
error from trying to create a Google OAuth credential with wrong fields:
{
"message": "[Link] requires property \"clientId\""
}
（See [73] for an OAuth example.）A 401 Unauthorized means missing/invalid API key. A
403 Forbidden can occur if your API key lacks required scopes (e.g. credential:update)
[17]. A 404 Not Found means the given workflow or credential ID doesn’t exist[17]. A
405 Method Not Allowed is returned if you try an unsupported method (e.g. GET
/credentials[13]).
Idempotency: POST requests (creating resources) are not idempotent – calling POST
/workflows twice will create two workflows. Using the same ID in URL for PUT or
DELETE is idempotent per HTTP semantics. The API does not currently support
idempotency keys.
Example Agent Interactions
Consider an AI agent (like Claude) automating workflow deployment. Given a workflow
JSON that references credential placeholders, the agent would:
• Parse the workflow JSON: Identify node credentials. E.g. if the
workflow JSON has
• "credentials": {"slackApi": {...}, "githubApi": {...}}
• the agent notes that slackApi and githubApi credentials are
required.
• Identify missing credentials: The agent checks which credentials
already exist in n8n Cloud (there’s no GET all, but it may track known IDs or
names). Any credential id marked as a placeholder (e.g.
"CREDENTIAL_ID_SLACK") is considered missing.
• Form API requests to create credentials: For each missing
credential, the agent constructs a POST request. For example, to create a Slack
credential:
• POST [Link]
Content-Type: application/json
X-N8N-API-KEY: <api-key>
{
"name": "Slack Bot",
"type": "slackApi",
"data": {
"accessToken": "xoxb-...BOT_TOKEN..."
}
}
• The agent then parses the response. On success it gets a new "id"
(e.g. "cfpXXMrPJqSfkMDQ"). The agent updates the workflow JSON, replacing
the placeholder ID with this new ID.
• Handle credential creation errors: If the POST fails (e.g. 400
Bad Request), the agent reads the error message. If it’s a validation error (missing
field), it can attempt to supply the missing data or report failure. A 403 would
indicate insufficient API scopes.
• Create or update the workflow: After all credentials are resolved,
the agent sends the workflow JSON to n8n. If creating a new workflow:
• POST [Link]
Content-Type: application/json
X-N8N-API-KEY: <api-key>
{ /* the full workflow JSON, now with real credential IDs */ }
• If updating an existing workflow, use PUT /api/v1/workflows/{id}
similarly.
• Handle workflow responses: On success, the API returns the
saved workflow object. If there is an error (e.g. 409 conflict or schema error), the
agent notes it and can retry or abort. The agent ensures to propagate any error
messages for debugging.
Example Agent I/O (pseudocode):
Input to Agent:
{
"intent": "deployWorkflow",
"workflow": { /* JSON with placeholder credential IDs */ }
}
Agent Actions:
- parseWorkflow(workflow) => finds credential types [slackApi, githubApi]
- for each type missing:
sendRequest("POST", "/credentials", { ...payload... }) => response (id, etc.)
updateWorkflowCredential(workflow, placeholderId, newId)
- sendRequest("POST", "/workflows", workflow) => get response or error
- handle errors/responses accordingly
This structured approach allows the agent to systematically provision credentials and
workflows via the n8n Cloud API, handling success and failure as described.
[1] [2] [3] [4] [5] N8N Import Workflow JSON: Complete Guide + File Format Examples
2025
[Link]
hosting-templates/n8n-import-workflow-json-complete-guide-file-format-examples-2025
[6] [7] Using an API playground | n8n Docs
[Link]
[8] [13] [14] n8n: scheduled work, backups and upgrades - Fresh/Brewed
[Link]
[9] Can n8n be used to authenticate with multiple different users? - Questions - n8n
Community
[Link]
users/20989
[10] Slack credentials | n8n Docs
[Link]
[11] [12] Authentication | n8n Docs
[Link]
[15] [16] [17] feat (public-api): update credentials by Shock3udt · Pull Request #18082 ·
n8n-io/n8n · GitHub
[Link]