HTTP API (poll): http_poll

Polls a JSON endpoint on the source’s schedule and stores one event per item. The generic path for the APIs no other connector covers: a weather service, a status page, a SaaS export, an endpoint of your own. Nested values are reachable by dotted name everywhere, so a label, a view filter or a trigger can watch current_weather.windspeed.

The webhook connector is for systems that call Tares. This one is for APIs Tares calls.

Set up

- name: weather_berlin
  connector: http_poll
  poll: 10m
  config:
    url: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true
    event_type: weather
    event_time_field: current_weather.time
    id_field: current_weather.time
    text_template: 'Berlin wind {current_weather.windspeed} km/h, {current_weather.temperature} C'
    labels:
      - { name: city, const: berlin, primary: true }
      - { name: windspeed, field: current_weather.windspeed, type: number }

The reply becomes events

• payload_key points at the part of the reply that is the payload, e.g. data or data.items. Empty means the entire JSON. An object there is one event; a list is one event per entry.
• event_time_field names the field holding the event’s time (ISO-8601 or epoch). Empty means the poll time.
• id_field is the deduplication key: an item whose value was seen in recent polls is not stored again. Use the entry’s id for a list API, or the reading’s own time for a single reading that only changes every few minutes. Empty stores every poll.
• event_type is the word views filter on and triggers count by, the same for every event; event_type_field takes it from a field of the item instead.
• text_template is the event summary, one line per event with values from the payload in braces, dotted names included. Empty stores the payload’s JSON.

The payload is stored as received, so labels declared later can still reach every field.

Authentication

One credential travels in one header. credential holds the whole value and is stored as a secret, never returned by the API and never exported. credential_header names the header, Authorization by default:

config:
  url: https://api.github.com/user
  credential: Bearer ghp_xxx          # a bearer token
  credential_header: Authorization

config:
  url: https://api.example.com/v1/readings
  credential: abc123                   # an API key
  credential_header: X-API-Key

Other headers the API wants on every request go in headers, which is not secret.

Rate limiting

A polled API has limits. The connector:

• refuses a poll under 10 seconds when the source is saved;
• backs off on a 429 or any 5xx: no request is made until the wait is over, and the wait doubles from the poll interval up to an hour. A 429 with Retry-After uses that value. The source’s health says “rate limited by the API, next try at HH:MM”;
• surfaces any other 4xx as a config error on the source’s health, with the status and a slice of the reply;
• clears the backoff on the next good poll.

Configuration

Verify

Open the source: Recent events shows each poll’s events with the summary line; Fields lists every field seen, dotted names included, with its coverage. A trigger on a number label, max(windspeed) > 62 over 15m, fires from the next reading that crosses it.