!

Legal Disclaimer

PipeAgent is a data distribution gateway. We do not own, verify, or endorse the data provided by third-party creators. Use at your own discretion.

Docs/consumer / feed type

Feed types (Consumer)

PipeAgent exposes three feed types so agents read the right shape of data: one live object, a versioned list, or an append-only timeline. This page is for reading feeds over the Consumer API. If you publish data, see Feed types (Provider — push).

Why it matters

Large HTML or unbounded JSON forces models to burn tokens on noise. Each feed type matches a common product pattern so you can fetch only what the agent needs (pagination, projection, filters within guardrails).

Cognitive shapes for LLMs: latest snapshot, bounded list, and event timeline

The three models (what you see when you GET)

1. Singleton

  • Use when: One current document — config, “latest snapshot,” status blob.
  • Read behavior: The API returns one JSON object representing the latest push. Each provider update replaces the previous document.

    • 2. Collection

  • Use when: A bounded list that updates as a set (rankings, product grids, “top N” tables).
  • Read behavior: You get a paginated view of the latest batch. Use limit / cursor parameters as documented in Quickstart. Ideal when the list is larger than a single model context.

    • 3. Stream

  • Use when: Time-ordered events — news, trades, activity logs.
  • Read behavior: New items are appended. Use cursors (and optional time windows) to page forward without re-reading the entire history.

    • ---

    Query guardrails & performance

    To keep latency predictable and tenants isolated, reads follow strict rules.

    1. Filtering: equality only on payload fields (eq)

    You can pass query parameters for top-level JSON fields inside payload, but only equality is supported.

  • Allowed: GET https://api.pipeagent.dev/v1/feed/{feed_id}?status=eq.bullish
  • Not allowed: Range (lt, gt) or pattern (ilike) on arbitrary JSON fields — they are disabled to avoid expensive scans.

    • 2. JSONPath projection

    Request only the slices or fields the agent needs. Supported shapes are simple paths and projections (no arbitrary filter expressions server-side).

  • Supported: Paths like $.metadata.price, $.items[0].price, array slices.
  • Not supported: Expressions such as $[?(@.price < 100)] (filter-in-jsonpath), to cap CPU.

    • 3. Pagination limits

  • Default page size: 20 records.
  • Maximum per request: 50 records (values above 50 are capped).
  • Applies to list reads, cursor reads, and bulk ids / details-style responses.

    • ---

    Consumer API examples

    Production gateway: https://api.pipeagent.dev. Paths below use /v1/feed/{feed_id} (see Quickstart for auth).

    Basic fetch

    Returns the singleton object, or a page of the latest collection / stream.

    bash
    GET https://api.pipeagent.dev/v1/feed/{feed_id}

    Stream time window

    For stream feeds, bound rows by event_timestamp (inclusive):

    bash
    GET https://api.pipeagent.dev/v1/feed/{feed_id}?start_time=2026-03-24T00:00:00Z&end_time=2026-03-24T23:59:59Z
  • start_time: inclusive lower bound (event_timestamp >= start_time)
  • end_time: inclusive upper bound (event_timestamp <= end_time)
  • ISO-8601 datetimes; combinable with cursor and limit.

    • JSONPath examples

    bash
    # First 5 elements
GET https://api.pipeagent.dev/v1/feed/{feed_id}?jsonpath=$[0:5]

# Pluck a field from each item
GET https://api.pipeagent.dev/v1/feed/{feed_id}?jsonpath=$[*].metadata.tags

    Details by ids

    bash
    GET https://api.pipeagent.dev/v1/feed/{feed_id}?ids=id1,id2

    ---

    Tips

  • Prefer collection when the stable list is longer than ~20 items.
  • Prefer stream for growing timelines.
  • Always prefer JSONPath (or narrow fields) so the model does not ingest unused columns.

    • ---

    Next: Feed types — Provider push API

    Version 1.0.4 - Premium Infrastructure