Pull Feeds (REST API)

Pull feeds let you fetch content collections on demand via standard HTTP GET requests. This is the simplest integration method — your system polls the API at regular intervals to check for updates.

How polling works

Your System                      Interplai API
    │                                │
    │── GET /v1/collections ────────▶│
    │◀── 200 (collection list) ──────│
    │                                │
    │── GET /v1/collections/:id ────▶│
    │◀── 200 (full collection) ──────│
    │                                │
    │  ... wait polling interval ... │
    │                                │
    │── GET /v1/collections/:id ────▶│
    │  (with If-None-Match ETag)     │
    │◀── 304 Not Modified ───────────│ ← no data transfer
    │                                │

Recommended polling intervals

Use case	Interval	Why
Live broadcast	5–10 seconds	Near real-time content updates
Digital signage	30–60 seconds	Balance freshness vs. bandwidth
Periodic sync	5–15 minutes	Batch processing, archival

Use ETags to save bandwidth

Always send the If-None-Match header with the ETag from the previous response. If the collection hasn't changed, the API returns 304 Not Modified with no body — saving bandwidth and processing time. See Caching.

Available endpoints

Endpoint	Description
GET /v1/collections	List all collections with pagination
GET /v1/collections/:id	Get a single collection with all content items

Response caching

All successful responses include a Cache-Control: public, max-age=30 header, meaning the response can be cached for up to 30 seconds. The single-collection endpoint also returns an ETag header for conditional requests.

When to use pull feeds

• You need to control exactly when data is fetched
• Your system doesn't support inbound HTTP (e.g. behind a firewall)
• You're building a simple integration with minimal infrastructure
• You want to avoid managing webhook endpoints and signature verification

For real-time, event-driven updates, see Push Feeds (Webhooks).