> ## Documentation Index
> Fetch the complete documentation index at: https://extended-openai-conversation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# REST Functions
> Fetch data from external REST APIs
REST functions retrieve data from external HTTP APIs and return the results to the AI. They're useful for integrating third-party services and real-time data sources.
## Configuration
```yaml theme={null}
function:
type: rest
resource: https://api.example.com/endpoint
value_template: "{{ value_json.data }}"
```
The URL endpoint to fetch data from
Jinja2 template to format the API response. The response is available as `value_json`.
## Template Processing
The `value_template` receives the API response as `value_json`:
```jinja2 Extract Array theme={null}
{{ value_json.items }}
```
```jinja2 Map Attributes theme={null}
{{ value_json | map(attribute="name") | list }}
```
```jinja2 Filter Data theme={null}
{{ value_json.results | selectattr('active', 'eq', true) | list }}
```
```jinja2 Format Output theme={null}
{% for item in value_json.data %}
- {{ item.name }}: {{ item.value }}
{% endfor %}
```
## Advanced Configuration
Add custom HTTP headers:
```yaml theme={null}
function:
type: rest
resource: https://api.example.com/data
headers:
Authorization: "Bearer YOUR_TOKEN"
Content-Type: "application/json"
value_template: "{{ value_json }}"
```
Change the HTTP method (default is GET):
```yaml theme={null}
function:
type: rest
resource: https://api.example.com/data
method: POST
payload: '{"key": "{{ param }}"}'
value_template: "{{ value_json }}"
```
Add query parameters:
```yaml theme={null}
function:
type: rest
resource: https://api.example.com/search
params:
q: "{{ query }}"
limit: 10
value_template: "{{ value_json.results }}"
```
## Use Cases
Integrate external services and data sources
Fetch current information like weather, stocks, or news
Query external search and lookup services
Monitor external service status and health
## Best Practices
APIs may return errors. Use safe filters and defaults:
```jinja2 theme={null}
{{ value_json.data | default('No data available') }}
```
Never hardcode API keys in function definitions. Use Home Assistant secrets:
```yaml theme={null}
headers:
Authorization: "Bearer !secret api_token"
```
Transform API responses into readable text for the AI:
```jinja2 theme={null}
{% for item in value_json.items %}
- {{ item.name }}: {{ item.status }}
{% endfor %}
```
Set reasonable timeouts for external APIs:
```yaml theme={null}
function:
type: rest
resource: https://api.example.com/slow-endpoint
timeout: 10
value_template: "{{ value_json }}"
```
## Debugging
Enable logging to see API requests and responses:
```yaml theme={null}
logger:
logs:
custom_components.extended_openai_conversation: debug
```
Check the logs for:
* Request URL and parameters
* Response status code
* Response body
* Template rendering errors
## Examples
### Get Friend Names
Fetch and format data from a JSON API:
```yaml theme={null}
- spec:
name: get_friend_names
description: Use this function to get friend names
parameters:
type: object
properties:
dummy:
type: string
description: Not used (placeholder)
function:
type: rest
resource: https://jsonplaceholder.typicode.com/users
value_template: '{{value_json | map(attribute="name") | list }}'
```
### Cryptocurrency Prices
```yaml theme={null}
- spec:
name: get_crypto_price
description: Get current cryptocurrency price
parameters:
type: object
properties:
symbol:
type: string
description: Crypto symbol (e.g., BTC, ETH)
required:
- symbol
function:
type: rest
resource: "https://api.coingecko.com/api/v3/simple/price"
params:
ids: "{{ symbol | lower }}"
vs_currencies: "usd"
value_template: >-
{{ symbol | upper }}: ${{ value_json[symbol | lower].usd }}
```
### Weather Data
```yaml theme={null}
- spec:
name: get_weather_external
description: Get weather from external API
parameters:
type: object
properties:
city:
type: string
description: City name
required:
- city
function:
type: rest
resource: "https://wttr.in/{{ city }}?format=j1"
value_template: >-
Weather in {{ city }}:
Temperature: {{ value_json.current_condition[0].temp_C }}°C
Condition: {{ value_json.current_condition[0].weatherDesc[0].value }}
Humidity: {{ value_json.current_condition[0].humidity }}%
```
## Next Steps
Extract web page data
Combine with other functions
Format REST data