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

function:
  type: rest
  resource: https://api.example.com/endpoint
  value_template: "{{ value_json.data }}"

resource · string · required

The URL endpoint to fetch data from

value_template · string

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:

Extract Array

{{ value_json.items }}

{{ value_json | map(attribute="name") | list }}

{{ value_json.results | selectattr('active', 'eq', true) | list }}

{% for item in value_json.data %}
- {{ item.name }}: {{ item.value }}
{% endfor %}

Advanced Configuration

Headers

Add custom HTTP headers:

function:
  type: rest
  resource: https://api.example.com/data
  headers:
    Authorization: "Bearer YOUR_TOKEN"
    Content-Type: "application/json"
  value_template: "{{ value_json }}"

Method

Change the HTTP method (default is GET):

function:
  type: rest
  resource: https://api.example.com/data
  method: POST
  payload: '{"key": "{{ param }}"}'
  value_template: "{{ value_json }}"

Parameters

Add query parameters:

function:
  type: rest
  resource: https://api.example.com/search
  params:
    q: "{{ query }}"
    limit: 10
  value_template: "{{ value_json.results }}"

Use Cases

Third-party APIs

Integrate external services and data sources

Real-time Data

Fetch current information like weather, stocks, or news

Search Services

Query external search and lookup services

Status Checks

Monitor external service status and health

Best Practices

1. Handle API errors

   APIs may return errors. Use safe filters and defaults:

   {{ value_json.data | default('No data available') }}
   
2. Secure API keys

   Never hardcode API keys in function definitions. Use Home Assistant secrets:

   headers:
     Authorization: "Bearer !secret api_token"
   
3. Format responses

   Transform API responses into readable text for the AI:

   {% for item in value_json.items %}
   - {{ item.name }}: {{ item.status }}
   {% endfor %}
   
4. Add timeouts

   Set reasonable timeouts for external APIs:

   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:

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:

- 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

- 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

- 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

Scrape Functions

Extract web page data

Composite Functions

Combine with other functions

Template Functions

Format REST data