# API Catalog

> >

- **Type:** Skill
- **Install:** `agentstack add skill-tonylofgren-aurora-smart-home-api-catalog`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tonylofgren](https://agentstack.voostack.com/s/tonylofgren)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tonylofgren](https://github.com/tonylofgren)
- **Source:** https://github.com/tonylofgren/aurora-smart-home/tree/main/api-catalog
- **Website:** https://instagram.com/roligaprojekt

## Install

```sh
agentstack add skill-tonylofgren-aurora-smart-home-api-catalog
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Catalog for Home Assistant

Reference skill for connecting external APIs and services to Home Assistant.

## Overview

This skill covers authentication patterns and working code examples for connecting popular
APIs to Home Assistant via three methods:

- **Node-RED** - HTTP request node flows (fastest to get running)
- **HA YAML** - `rest` sensor and `rest_command` (good for simple polling)
- **Custom integration** - Full HACS-publishable Python component (use `ha-integration` skill)

## The Iron Law

```
CREDENTIALS IN SECRETS - NEVER HARDCODED IN FLOWS OR YAML
```

API keys belong in Node-RED credentials, ESPHome secrets.yaml, or HA `secrets.yaml`.
Never paste real tokens into chat, flows that get exported, or YAML committed to git.

## How to Use This Skill

1. User mentions an API or service by name
2. Read the relevant reference file for auth setup and endpoints
3. Generate working code for the user's chosen method (Node-RED / YAML / integration)
4. Include credential setup instructions

## Reference Files

| Category | File | APIs Covered |
|----------|------|-------------|
| Energy & electricity | `references/energy-apis.md` | Tibber, Nordpool, Energi Data Service |
| Weather | `references/weather-apis.md` | SMHI, OpenWeatherMap, yr.no, Tomorrow.io |
| Transport | `references/transport-apis.md` | SL, Trafikverket, Resrobot, Entur (NO) |
| Smart home clouds | `references/smarthome-apis.md` | Shelly Cloud, Tuya IoT, Philips Hue, IKEA Dirigera |
| Global / other | `references/global-apis.md` | OpenAI, Spotify, Google Calendar, Telegram, GitHub |

## Authentication Patterns at a Glance

| Pattern | How it works | Examples |
|---------|-------------|----------|
| API key in header | `Authorization: Bearer {key}` or `X-API-Key: {key}` | Tibber, OpenAI |
| API key in URL | `?appid={key}` appended to URL | OpenWeatherMap |
| OAuth2 | Get access token first, refresh periodically | Spotify, Google |
| Local token | One-time press-button auth on device | Philips Hue |
| No auth | Public API, no credentials needed | SMHI, yr.no, Nordpool |
| Basic auth | Username + password Base64-encoded | Some local devices |

## Output Methods

For each API, generate code for the method the user needs:

**Node-RED:** `http request` node + `function` node to parse + `api-call-service` to push to HA
**HA YAML:** `rest` sensor platform or `rest_command` under `configuration.yaml`
**Full integration:** Use `ha-integration` skill with the `polling-integration` template

## Common Patterns

### Node-RED: API key in header
```json
{
  "type": "http request",
  "method": "GET",
  "url": "https://api.example.com/data",
  "headers": {"Authorization": "Bearer {{env.API_KEY}}"},
  "ret": "obj"
}
```

### Node-RED: GraphQL (Tibber-style)
```json
{
  "type": "http request",
  "method": "POST",
  "url": "https://api.tibber.com/v1-beta/gql",
  "headers": {
    "Authorization": "Bearer {{env.TIBBER_TOKEN}}",
    "Content-Type": "application/json"
  },
  "payload": "{\"query\": \"{ viewer { homes { currentSubscription { priceInfo { current { total } } } } } }\"}",
  "ret": "obj"
}
```

### HA YAML: REST sensor
```yaml
rest:
  - scan_interval: 300
    resource: https://api.example.com/current
    headers:
      Authorization: !secret example_api_key
    sensor:
      - name: "Example Value"
        value_template: "{{ value_json.data.value }}"
        unit_of_measurement: "°C"
```

## Pre-Output Checklist

- [ ] Credentials use `!secret` (YAML), Node-RED credentials, or env vars - never hardcoded
- [ ] Rate limits respected (include `scan_interval` or flow timer accordingly)
- [ ] Error handling included (Node-RED catch node or YAML timeout)
- [ ] For OAuth2: refresh token flow explained
- [ ] Attribution: which API endpoint, what data it returns

## Integration

**Pairs with:**
- `node-red` skill - for flow JSON implementation
- `ha-yaml` skill - for YAML sensor and automation using the fetched data
- `ha-integration` skill - for building a full HACS-publishable Python integration

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tonylofgren](https://github.com/tonylofgren)
- **Source:** [tonylofgren/aurora-smart-home](https://github.com/tonylofgren/aurora-smart-home)
- **License:** MIT
- **Homepage:** https://instagram.com/roligaprojekt

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tonylofgren-aurora-smart-home-api-catalog
- Seller: https://agentstack.voostack.com/s/tonylofgren
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.