Omnivery Datafeeder

Secure, authenticated delivery of curated datafeeds to authorized partners.

The Datafeeder service delivers periodically-refreshed datasets over HTTPS. Each feed is a cached snapshot that is rebuilt on a schedule; you always receive the last completed snapshot, so responses are fast and consistent.

Access is granted per partner. If you do not yet have credentials, contact your Omnivery representative to request an API key and to be granted access to the feeds relevant to you.

Authentication

All requests require TLS and a valid API key. Provide your key with either an Authorization bearer header (preferred) or the X-API-Key header:

Authorization: Bearer <your-api-key>
# or
X-API-Key: <your-api-key>

Requests without a valid key receive 401 Unauthorized. A key that is valid but not permitted for a given feed receives 403 Forbidden. Keys are issued and scoped by the operator — keep yours secret.

Discover the feeds available to you

Your key is scoped to a specific set of feeds. To see exactly which feeds you may access, call the listing endpoint:

GET/api/v1/feeds

Returns only the feeds your API key is authorized to retrieve.

curl -H "Authorization: Bearer <your-api-key>" \
     https://<host>/api/v1/feeds

Example response:

{
  "feeds": [
    {
      "name": "example-feed",
      "default_format": "json",
      "formats": ["csv", "json"],
      "path": "/api/v1/feeds/example-feed",
      "schedule": { "at": ["02:00", "14:00"], "timezone": "UTC" },
      "ready": true,
      "generated_at": "2026-07-15T02:00:03Z",
      "next_refresh": "2026-07-15T14:00:00Z"
    }
  ]
}

Use the name (or path) from this response to retrieve a feed. The listing reflects your own authorization only; it does not describe the full catalog.

schedule describes how often the snapshot is rebuilt — either a rolling interval ({ "every": "6h" }) or fixed daily build times ({ "at": ["02:00", "14:00"], "timezone": "UTC" }). generated_at is when the snapshot you would receive now was built, and next_refresh is when the next rebuild is due.

Retrieve a feed

GET/api/v1/feeds/{name}?format=json|csv

curl -H "Authorization: Bearer <your-api-key>" \
     "https://<host>/api/v1/feeds/<name>?format=json"

Each feed has a default format; override it with ?format=json or ?format=csv.
No other query parameters are accepted — a feed is a fixed snapshot, not a live query. Any other parameter returns 400.
The X-Generated-At response header carries the snapshot's UTC timestamp (ISO 8601).
If a feed has not completed its first build yet, the response is 503; retry shortly.

Response status codes

Code	Meaning
`200`	Snapshot returned.
`400`	Unsupported format or an unexpected query parameter.
`401`	Missing or invalid API key.
`403`	Key not authorized for this feed.
`404`	No such feed.
`503`	Snapshot not yet available.

Health

A public, unauthenticated liveness probe is available at GET /healthz.