api-catalog

Name: api-catalog
Author: tonylofgren

33installs3forks

How to install api-catalog?

tonylofgren/aurora-smart-home/api-catalog

$npx -y skills add tonylofgren/aurora-smart-home --skill api-catalog

Installs into the current project.

Summary

Reference guide for connecting popular APIs to Home Assistant via Node-RED, YAML, or custom integrations. Covers authentication, endpoints, and complete working examples for: energy APIs (Tibber, Nordpool), weather (SMHI, OpenWeatherMap, yr.no), transport (SL, Trafikverket, Resro

Files · 1

View on GitHub

SKILL.md

1	# API Catalog for Home Assistant
2
3	Reference skill for connecting external APIs and services to Home Assistant.
4
5	## Overview
6
7	This skill covers authentication patterns and working code examples for connecting popular
8	APIs to Home Assistant via three methods:
9
10	- Node-RED - HTTP request node flows (fastest to get running)
11	- HA YAML - `rest` sensor and `rest_command` (good for simple polling)
12	- Custom integration - Full HACS-publishable Python component (use `ha-integration` skill)
13
14	## The Iron Law
15
16	```
17	CREDENTIALS IN SECRETS - NEVER HARDCODED IN FLOWS OR YAML
18	```
19
20	API keys belong in Node-RED credentials, ESPHome secrets.yaml, or HA `secrets.yaml`.
21	Never paste real tokens into chat, flows that get exported, or YAML committed to git.
22
23	## How to Use This Skill
24
25	1. User mentions an API or service by name
26	2. Read the relevant reference file for auth setup and endpoints
27	3. Generate working code for the user's chosen method (Node-RED / YAML / integration)
28	4. Include credential setup instructions
29
30	## Reference Files
31
32	\| Category \| File \| APIs Covered \|
33	\|----------\|------\|-------------\|
34	\| Energy & electricity \| `references/energy-apis.md` \| Tibber, Nordpool, Energi Data Service \|
35	\| Weather \| `references/weather-apis.md` \| SMHI, OpenWeatherMap, yr.no, Tomorrow.io \|
36	\| Transport \| `references/transport-apis.md` \| SL, Trafikverket, Resrobot, Entur (NO) \|
37	\| Smart home clouds \| `references/smarthome-apis.md` \| Shelly Cloud, Tuya IoT, Philips Hue, IKEA Dirigera \|
38	\| Global / other \| `references/global-apis.md` \| OpenAI, Spotify, Google Calendar, Telegram, GitHub \|
39
40	## Authentication Patterns at a Glance
41
42	\| Pattern \| How it works \| Examples \|
43	\|---------\|-------------\|----------\|
44	\| API key in header \| `Authorization: Bearer {key}` or `X-API-Key: {key}` \| Tibber, OpenAI \|
45	\| API key in URL \| `?appid={key}` appended to URL \| OpenWeatherMap \|
46	\| OAuth2 \| Get access token first, refresh periodically \| Spotify, Google \|
47	\| Local token \| One-time press-button auth on device \| Philips Hue \|
48	\| No auth \| Public API, no credentials needed \| SMHI, yr.no, Nordpool \|
49	\| Basic auth \| Username + password Base64-encoded \| Some local devices \|
50
51	## Output Methods
52
53	For each API, generate code for the method the user needs:
54
55	Node-RED: `http request` node + `function` node to parse + `api-call-service` to push to HA
56	HA YAML: `rest` sensor platform or `rest_command` under `configuration.yaml`
57	Full integration: Use `ha-integration` skill with the `polling-integration` template
58
59	## Common Patterns
60
61	### Node-RED: API key in header
62	```json
63	{
64	"type": "http request",
65	"method": "GET",
66	"url": "https://api.example.com/data",
67	"headers": {"Authorization": "Bearer {{env.API_KEY}}"},
68	"ret": "obj"
69	}
70	```
71
72	### Node-RED: GraphQL (Tibber-style)
73	```json
74	{
75	"type": "http request",
76	"method": "POST",
77	"url": "https://api.tibber.com/v1-beta/gql",
78	"headers": {
79	"Authorization": "Bearer {{env.TIBBER_TOKEN}}",
80	"Content-Type": "application/json"
81	},
82	"payload": "{\"query\": \"{ viewer { homes { currentSubscription { priceInfo { current { total } } } } } }\"}",
83	"ret": "obj"
84	}
85	```
86
87	### HA YAML: REST sensor
88	```yaml
89	rest:
90	- scan_interval: 300
91	resource: https://api.example.com/current
92	headers:
93	Authorization: !secret example_api_key
94	sensor:
95	- name: "Example Value"
96	value_template: "{{ value_json.data.value }}"
97	unit_of_measurement: "°C"
98	```
99
100	## Pre-Output Checklist
101
102	- [ ] Credentials use `!secret` (YAML), Node-RED credentials, or env vars - never hardcoded
103	- [ ] Rate limits respected (include `scan_interval` or flow timer accordingly)
104	- [ ] Error handling included (Node-RED catch node or YAML timeout)
105	- [ ] For OAuth2: refresh token flow explained
106	- [ ] Attribution: which API endpoint, what data it returns
107
108	## Integration
109
110	Pairs with:
111	- `node-red` skill - for flow JSON implementation
112	- `ha-yaml` skill - for YAML sensor and automation using the fetched data
113	- `ha-integration` skill - for building a full HACS-publishable Python integration

People who liked this also viewed

6 picks

Type

api-catalog

33installs3forks

View on GitHub

How to install api-catalog?

tonylofgren/aurora-smart-home/api-catalog

$npx -y skills add tonylofgren/aurora-smart-home --skill api-catalog

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Catalog for Home Assistant
2
3	Reference skill for connecting external APIs and services to Home Assistant.
4
5	## Overview
6
7	This skill covers authentication patterns and working code examples for connecting popular
8	APIs to Home Assistant via three methods:
9
10	- Node-RED - HTTP request node flows (fastest to get running)
11	- HA YAML - `rest` sensor and `rest_command` (good for simple polling)
12	- Custom integration - Full HACS-publishable Python component (use `ha-integration` skill)
13
14	## The Iron Law
15
16	```
17	CREDENTIALS IN SECRETS - NEVER HARDCODED IN FLOWS OR YAML
18	```
19
20	API keys belong in Node-RED credentials, ESPHome secrets.yaml, or HA `secrets.yaml`.
21	Never paste real tokens into chat, flows that get exported, or YAML committed to git.
22
23	## How to Use This Skill
24
25	1. User mentions an API or service by name
26	2. Read the relevant reference file for auth setup and endpoints
27	3. Generate working code for the user's chosen method (Node-RED / YAML / integration)
28	4. Include credential setup instructions
29
30	## Reference Files
31
32	\| Category \| File \| APIs Covered \|
33	\|----------\|------\|-------------\|
34	\| Energy & electricity \| `references/energy-apis.md` \| Tibber, Nordpool, Energi Data Service \|
35	\| Weather \| `references/weather-apis.md` \| SMHI, OpenWeatherMap, yr.no, Tomorrow.io \|
36	\| Transport \| `references/transport-apis.md` \| SL, Trafikverket, Resrobot, Entur (NO) \|
37	\| Smart home clouds \| `references/smarthome-apis.md` \| Shelly Cloud, Tuya IoT, Philips Hue, IKEA Dirigera \|
38	\| Global / other \| `references/global-apis.md` \| OpenAI, Spotify, Google Calendar, Telegram, GitHub \|
39
40	## Authentication Patterns at a Glance
41
42	\| Pattern \| How it works \| Examples \|
43	\|---------\|-------------\|----------\|
44	\| API key in header \| `Authorization: Bearer {key}` or `X-API-Key: {key}` \| Tibber, OpenAI \|
45	\| API key in URL \| `?appid={key}` appended to URL \| OpenWeatherMap \|
46	\| OAuth2 \| Get access token first, refresh periodically \| Spotify, Google \|
47	\| Local token \| One-time press-button auth on device \| Philips Hue \|
48	\| No auth \| Public API, no credentials needed \| SMHI, yr.no, Nordpool \|
49	\| Basic auth \| Username + password Base64-encoded \| Some local devices \|
50
51	## Output Methods
52
53	For each API, generate code for the method the user needs:
54
55	Node-RED: `http request` node + `function` node to parse + `api-call-service` to push to HA
56	HA YAML: `rest` sensor platform or `rest_command` under `configuration.yaml`
57	Full integration: Use `ha-integration` skill with the `polling-integration` template
58
59	## Common Patterns
60
61	### Node-RED: API key in header
62	```json
63	{
64	"type": "http request",
65	"method": "GET",
66	"url": "https://api.example.com/data",
67	"headers": {"Authorization": "Bearer {{env.API_KEY}}"},
68	"ret": "obj"
69	}
70	```
71
72	### Node-RED: GraphQL (Tibber-style)
73	```json
74	{
75	"type": "http request",
76	"method": "POST",
77	"url": "https://api.tibber.com/v1-beta/gql",
78	"headers": {
79	"Authorization": "Bearer {{env.TIBBER_TOKEN}}",
80	"Content-Type": "application/json"
81	},
82	"payload": "{\"query\": \"{ viewer { homes { currentSubscription { priceInfo { current { total } } } } } }\"}",
83	"ret": "obj"
84	}
85	```
86
87	### HA YAML: REST sensor
88	```yaml
89	rest:
90	- scan_interval: 300
91	resource: https://api.example.com/current
92	headers:
93	Authorization: !secret example_api_key
94	sensor:
95	- name: "Example Value"
96	value_template: "{{ value_json.data.value }}"
97	unit_of_measurement: "°C"
98	```
99
100	## Pre-Output Checklist
101
102	- [ ] Credentials use `!secret` (YAML), Node-RED credentials, or env vars - never hardcoded
103	- [ ] Rate limits respected (include `scan_interval` or flow timer accordingly)
104	- [ ] Error handling included (Node-RED catch node or YAML timeout)
105	- [ ] For OAuth2: refresh token flow explained
106	- [ ] Attribution: which API endpoint, what data it returns
107
108	## Integration
109
110	Pairs with:
111	- `node-red` skill - for flow JSON implementation
112	- `ha-yaml` skill - for YAML sensor and automation using the fetched data
113	- `ha-integration` skill - for building a full HACS-publishable Python integration

People who liked this also viewed

6 picks

Type