Skip to content

Update templates API endpoints and document missing parameters #3000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
imchairmanm merged 6 commits into from
Mar 20, 2025
Merged

Update templates API endpoints and document missing parameters #3000

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
59fbdc4
Update templates API endpoints and document missing parameters
imchairmanm Mar 19, 2025
ea4f3d7
Fix table formatting
imchairmanm Mar 19, 2025
084a70d
Merge branch 'main' into DOC-1422/update-tempates-api-endpoints
imchairmanm Mar 19, 2025
23a95a1
Add schemas to template files
imchairmanm Mar 19, 2025
aef9381
Merge branch 'DOC-1422/update-tempates-api-endpoints' of github.com:n…
imchairmanm Mar 19, 2025
cfddc2b
Adjust wording
imchairmanm Mar 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
320 changes: 313 additions & 7 deletions _snippets/workflows/templates/custom-templates-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,329 @@
In your environment variables, set `N8N_TEMPLATES_HOST` to the base URL of your API.

### Endpoints

Your API must provide the same endpoints and data structure as n8n's.

The endpoints are:

| Method | Path |
| ------ | ---- |
| GET | /templates/workflows/`<id>` |
| GET | /templates/workflows |
| GET | /templates/search |
| GET | /templates/collections/`<id>` |
| GET | /templates/collections |
| GET | /templates/categories |
| GET | /health |

To learn about the data structure, try out n8n's API endpoints:
### Query parameters

The `/templates/search` endpoint accepts the following query parameters:

| Parameter | Type | Description |
|------------|----------------------------------------------|--------------------------------------------------|
| `page` | integer | The page of results to return |
| `rows` | integer | The maximum number of results to return per page |
| `category` | comma-separated list of strings (categories) | The categories to search within |
| `search` | string | The search query |

The `/templates/collections` endpoint accepts the following query parameters:

| Parameter | Type | Description |
|------------|----------------------------------------------|---------------------------------|
| `category` | comma-separated list of strings (categories) | The categories to search within |
| `search` | string | The search query |

### Data schema

You can explore the data structure of the items in the response object returned by endpoints here:

??? note "Show `workflow` item data schema"
```json title="Workflow item data schema"
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Generated schema for Root",
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
},
"totalViews": {
"type": "number"
},
"price": {},
"purchaseUrl": {},
"recentViews": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"required": [
"username",
"verified"
]
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"icon": {
"type": "string"
},
"name": {
"type": "string"
},
"codex": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"resources": {
"type": "object",
"properties": {
"generic": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"icon": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"url",
"label"
]
}
},
"primaryDocumentation": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
]
}
}
},
"required": [
"primaryDocumentation"
]
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"nodeVersion": {
"type": "string"
},
"codexVersion": {
"type": "string"
}
},
"required": [
"categories"
]
}
}
},
"group": {
"type": "string"
},
"defaults": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"color": {
"type": "string"
}
},
"required": [
"name"
]
},
"iconData": {
"type": "object",
"properties": {
"icon": {
"type": "string"
},
"type": {
"type": "string"
},
"fileBuffer": {
"type": "string"
}
},
"required": [
"type"
]
},
"displayName": {
"type": "string"
},
"typeVersion": {
"type": "number"
},
"nodeCategories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
}
},
"required": [
"id",
"icon",
"name",
"codex",
"group",
"defaults",
"iconData",
"displayName",
"typeVersion"
]
}
}
},
"required": [
"id",
"name",
"totalViews",
"price",
"purchaseUrl",
"recentViews",
"createdAt",
"user",
"nodes"
]
}
```

??? note "Show `category` item data schema"
```json title="Category item data schema"
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
```

??? note "Show `collection` item data schema"
```json title="Collection item data schema"
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {
"type": "number"
},
"rank": {
"type": "number"
},
"name": {
"type": "string"
},
"totalViews": {},
"createdAt": {
"type": "string"
},
"workflows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
}
},
"required": [
"id"
]
}
},
"nodes": {
"type": "array",
"items": {}
}
},
"required": [
"id",
"rank",
"name",
"totalViews",
"createdAt",
"workflows",
"nodes"
]
}
```

You can also interactively explore n8n's API endpoints:

[https://api.n8n.io/templates/categories](https://api.n8n.io/templates/categories)
[https://api.n8n.io/templates/collections](https://api.n8n.io/templates/collections)
[https://api.n8n.io/templates/search](https://api.n8n.io/templates/search)
[https://api.n8n.io/health](https://api.n8n.io/health)

[https://api.n8n.io/templates/categories](https://api.n8n.io/templates/categories){:target=_blank .external-link}
[https://api.n8n.io/templates/collections](https://api.n8n.io/templates/collections){:target=_blank .external-link}
[https://api.n8n.io/templates/workflows](https://api.n8n.io/templates/workflows){:target=_blank .external-link}
[https://api.n8n.io/health](https://api.n8n.io/health){:target=_blank .external-link}

You can also [contact us](mailto:help@n8n.io) for more support.
You can [contact us](mailto:help@n8n.io) for more support.

Check warning on line 329 in _snippets/workflows/templates/custom-templates-library.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-microsoft.We] Try to avoid using first-person plural like 'us'.

Raw Output:
{"message": "[from-microsoft.We] Try to avoid using first-person plural like 'us'.", "location": {"path": "_snippets/workflows/templates/custom-templates-library.md", "range": {"start": {"line": 329, "column": 18}}}, "severity": "WARNING"}