Skip to Content
Tares

How do I bring JSON API endpoints into an AI SRE’s context?

Tares brings a JSON API endpoint into an AI SRE’s context with the http_poll connector, which calls the endpoint on a schedule and stores one event per item. You describe the request once, press Discover, and Tares fills in the rest from a real reply. The events join the same timeline the AI SRE reads, so labels, triggers and correlation work on your API data like any other source.

How it works

The http_poll connector is for APIs that Tares calls itself. No script runs on your side. On every poll Tares sends the request and turns the reply into events.

  • Which part of the reply: payload_key points at the part that is the payload, such as data or data.items. Empty means the entire JSON. An object is one event. A list is one event per entry.
  • When it happened: event_time_field names the field with the event’s time, in ISO-8601 or epoch. Empty means the poll time.
  • No duplicates: 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 changes every few minutes. Empty stores every poll.
  • Event type: event_type is the same word for every event (default api_reading). event_type_field reads it from a field of the item instead.
  • Summary line: text_template writes one line per event from payload values. Dotted names work. Empty stores the payload’s JSON.

The payload is stored as received, so labels you declare later can still reach every field. Nested values are reachable by dotted name in labels, trigger filters and trigger conditions, for example current_weather.windspeed.

A polled API has limits, and the connector respects them:

  • It refuses a poll under 10 seconds when you save the source.
  • On a 429 or any 5xx it stops requesting until the wait is over. The wait doubles from the poll interval up to an hour, and a 429 with Retry-After uses that value. The source’s health shows when the next try is.
  • Any other 4xx shows as a config error on the source’s health, with the status and a slice of the reply.
  • The next good poll clears the backoff.

Set it up

  1. Open Sources, Add source, HTTP API (poll). You can also ask a connected agent, or send the same object with POST /api/sources.
  2. Fill in the request: method (GET by default, or POST with a body object), the URL with its query string, and any extra headers. The URL is checked on save: http or https, a host, no spaces.
  3. Add a credential if the API wants one. It 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 and defaults to Authorization. For an API key it looks like this:
config:
  url: https://api.example.com/v1/readings
  credential: abc123                   # an API key
  credential_header: X-API-Key
  1. Press Discover. Tares calls the API once, shows the reply it got, and fills in what becomes an event. Pick the entity key from the fields it saw, then create the source.
  2. Check the result. The finished source looks like this:
- 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 }
  1. Verify on the source page. Recent events shows each poll’s events with the summary line. Fields lists every field seen, dotted names included, with its coverage. Full field reference and more examples are on the HTTP API (poll) connector page.

What you get

  • Each item your endpoint returns becomes an event in the timeline, stamped with the time from the payload or the poll time.
  • Repeated readings are not stored twice when you set id_field.
  • Number labels feed triggers directly. A trigger such as max(windspeed) > 62 over 15m fires from the next reading that crosses the threshold.
  • The stored payload is lossless, so a label added tomorrow can still read a field you ignored today.
  • A secret credential that is never returned or exported, and polling that backs off on its own when the API pushes back.
  • Works for any JSON API: a weather service, a status page, a SaaS export or an endpoint of your own.

When something else fits

  • If the data sits in a database table, use the Postgres connector. It reads new and changed rows on a cursor column such as an autoincrement id or updated_at, rather than polling an endpoint on a schedule and storing one event per item.
  • If the system should call Tares instead of Tares calling it, the webhook connector fits better, because http_poll is only for APIs Tares can reach and call.
  • If you need data faster than every 10 seconds, http_poll is not the right tool, since it refuses shorter intervals.

Still stuck? Get help

Last updated on
Quickstart