Sources

A feed, on a schedule

A source is an endpoint plus a fetch schedule — registered once, then fetched on its own cron, politely, with auth when the origin needs it.

Formats

The formats the web uses

The source's type selects the parser — each one reading the format's real conventions, not a lowest common denominator.

RSS 2.0 — items keyed by guid (falling back to link), with content:encoded and dc:creator read when present.
Atom — entries keyed by their entry id.
JSON Feed 1.1 — items keyed by id, body from content_html falling back to content_text.
Endpoints are normalized into a canonical URL that's unique across live sources — registering a duplicate is rejected.

mutation {
  feeds { sources { add(input: {
    name: "Example News"
    configuration: {
      type: RSS
      endpoint: "https://example.com/feed.xml"
      cronInterval: "0 * * * *"
      enabled: true
    }
  }) { id url } } }
}

Scheduling

Fetches that don't waste a byte

Every enabled source runs on its own cron — and every scheduled fetch is conditional, so unchanged feeds cost one round trip and nothing more.

Each source gets its own scheduled job from its cronInterval; enabling creates it, disabling removes it, and edits reschedule it from scratch.
ETag and Last-Modified validators are stored after each fetch and sent back as If-None-Match / If-Modified-Since — a 304 short-circuits to a no-op.
Fetches run as durable jobs on the background job infrastructure; a non-2xx response fails the fetch and records it.
A manual fetch is always forced — it omits the validators so the origin returns the full feed, which is how you backfill after an ingestion change.

fetch log

09:00cron → GET · 304 Not Modifiedno-op

10:00cron → GET · 200 · 3 new itemsingested

10:12manual → forced, full feedbackfilled

Auth & ownership

Private origins, private sources

Protected feeds get outbound credentials; personal feeds get personal sources — with the secret handled the way secrets should be.

Outbound auth types: none, basic, bearer, or API key.
The one secret value is write-only — set via authSecret, stored in the platform's configuration service, never returned by any query. Deleting the source deletes the secret.
Sources are managed (platform-wide, admin-gated) or user (private to one profile, every operation ownership-gated).
A user source can't claim a canonical URL a managed source already uses.

source configuration

TypeRSS

Schedule0 * * * *

AuthBearer

Secretwrite-only

OwnershipManaged

Keep exploring

A feed, on a schedule

The formats the web uses

Fetches that don't waste a byte

Private origins, private sources

More on Feeds

Feeds overview

Ingestion

Serving & subscriptions