Feed

List unified feed items

GET /api/feed-items.json

Markdown · Authoritative OpenAPI

Request policy

Operation: getFeedItems
Access: anonymous
Automatic retries: None
Redirects: Returned to the caller without following
Request body limit: No request body
Pagination: One page per call. Explicit iteration defaults to at most 10 pages, 1,000 items, and 32 MiB; reaching a bound reports incomplete execution.

Parameters

limit number

Requested page size (default 50). Numeric values are floored and clamped to 1–100.

cursor string

Opaque cursor copied from a returned pagination link. Arbitrary strings are rejected with 400; windowed feed cursors must retain their original filters.

sort string

Sort field and direction (e.g., "year:desc", "addedAt:asc")

facets string

Include facet metadata in response meta (set to 1)

mode string

Optional upcoming (soonest first) or past (newest first) window; omitted preserves the unpartitioned feed

Allowed: "upcoming" | "past"

asOf string (date-time)

Frozen UTC boundary in YYYY-MM-DDTHH:mm:ss.sssZ format; requires mode

kind string

Filter by comma-separated kind values

source string

Filter by comma-separated source values

year number

Filter by feed content year

from string (date)

Include items on or after this YYYY-MM-DD content date

to string (date)

Include items before this YYYY-MM-DD content date

q string

Case-insensitive search across feed item fields

Request headers

API-Version (optional) — Header-based API version selection. Omit it, send an empty value, or send 1.0.0; surrounding whitespace is ignored.
Idempotency-Key (optional) — Accepted for clients that attach a key uniformly. GET, HEAD, and OPTIONS are already safe and intrinsically idempotent, so read responses are not stored in an idempotency replay cache.

Responses

200

List response for feed-items

Response headers

{
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  },
  "ETag": {
    "description": "Entity tag for conditional requests",
    "schema": {
      "type": "string"
    }
  },
  "Cache-Control": {
    "description": "Caching directives",
    "schema": {
      "type": "string"
    }
  },
  "X-Total-Count": {
    "description": "Total number of items",
    "schema": {
      "type": "integer"
    }
  },
  "Link": {
    "description": "RFC 8288 Web Linking header with pagination links",
    "schema": {
      "type": "string"
    }
  },
  "Link-Template": {
    "description": "RFC 9652 Link-Template header with query parameter templates",
    "schema": {
      "type": "string"
    }
  },
  "Deprecation": {
    "description": "RFC 9745 lifecycle deprecation signal",
    "schema": {
      "type": "string"
    }
  },
  "Sunset": {
    "description": "RFC 8594 lifecycle sunset date (HTTP IMF-fixdate)",
    "schema": {
      "type": "string",
      "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$",
      "examples": [
        "Sun, 06 Sep 2026 17:40:13 GMT"
      ]
    }
  }
}

application/json

object

Schema details

data FeedItem[] required

Schema details

FeedItem

Schema details

id string required

canonicalId string required

kind string required

source string required

title string required

itemPath string required

url string required

activityAt string required (date-time)

activityYear number required

contentTimestamp string required (date-time)

timestamp string required (date-time)

summary string required

year number required

slug string

writingSource string

Allowed: "substack" | "cloudflare" | "other"

videoId string

embedUrl string (uri)

movieType string

Allowed: "movie" | "tv"

category string

playlistId string

mixId string

mixSource string

Allowed: "youtube" | "soundcloud" | "unknown"

albumId string

trackId string

appleUrl string (uri)

spotifyUrl string (uri)

tweetId string

author string

eventType string

repo string

score number

reasons string[]

Schema details

string

notes string

domain string

siteName string

description string

image string

alt string

caption string

bookAuthor string

displayYear number

stravaActivityId string

embedToken string

routeSummaryPolyline string

sportType string

distanceMeters number

movingTimeSeconds number

totalElevationGainMeters number

sportingEvent object

Schema details

sport string required

league string required

date string required (date)

startTime string required

Schema details

string (date-time)

unknown

endTime string required

Schema details

string (date-time)

unknown

timeZone string required

schedule object

Schema details

necessity string required

Allowed: "unknown" | "required" | "if-necessary" | "not-needed"

state string required

Allowed: "scheduled" | "unconfirmed" | "postponed" | "cancelled" | "completed"

timeConfirmed boolean required

providerEventId string

checkedAt string (date-time)

status string required

Allowed: "scheduled" | "completed" | "cancelled"

experience object required

Schema details

kind string required

Allowed: "in-person" | "watch"

status string required

Allowed: "planned" | "completed"

venue object required

Schema details

object

Schema details

name string required

city string

region string

country string

unknown

competitors object[] required

Schema details

object

Schema details

designation string required

Allowed: "away" | "home"

team object required

score number

result string

Allowed: "win" | "loss" | "tie"

referenceUrl string required (uri)

semantic object

Schema details

creators object[]

Schema details

object

Schema details

name string required

role string

parent object

Schema details

kind string required

Allowed: "album" | "podcast-show" | "series" | "tour"

title string required

canonicalId string

position string

genres string[]

Schema details

string

topics string[]

Schema details

string

publication string

venue object

Schema details

name string required

city string

region string

personal object

Schema details

rating number

experience string

Allowed: "in-person" | "watch"

format string

Allowed: "kindle" | "paperback" | "hardcover" | "print"

sourceSignals string[]

Schema details

string

Allowed: "authored" | "retweeted" | "liked" | "bookmarked"

readCount number

dateRead string (date-time)

counts object

Schema details

tracks number

songs number

sets number

encores number

pages number

performers number

achievements number

activity object

Schema details

averageSpeedMetersPerSecond number

achievementCount number

trainer boolean

commute boolean

manual boolean

sourceLabel string

camera string

endAt string (date-time)

company string

occurredAt string

meta PaginationMeta required

Schema details

totalCount number required

pageSize number required

timestamp string required (date-time)

rowsRead number

Rows materialized by the bounded D1 list window, when available.

boundedD1Window boolean

The list was served through a bounded D1 window.

facets object

correction object

Schema details

original string required

resolved string required

applied boolean required

kind string required

Allowed: "alias" | "fuzzy"

links PaginationLinks required

Schema details

self string required (uri)

first string required (uri)

next string (uri)

prev string (uri)

last string required (uri)

text/csv

string

304

Not Modified

400

Bad Request

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

406

Not Acceptable

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

429

Public REST request limit exceeded

Response headers

{
  "Retry-After": {
    "description": "Seconds before the request should be retried",
    "schema": {
      "type": "integer",
      "enum": [
        60
      ]
    }
  },
  "RateLimit": {
    "description": "Current quota state for the exhausted public-rest policy",
    "schema": {
      "type": "string"
    }
  },
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  }
}

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

503

Portable location provenance is incomplete, so the export is unavailable

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

Examples

Examples use synthetic fixture values. Replace fixture identifiers with public IDs returned by the service. Request bodies and precise locations are transient; keep them out of logs.

curl

curl --fail-with-body --max-time 30 --max-filesize 16777216 --request GET 'https://irvinebroque.com/api/feed-items.json' --header 'Accept: application/json'

TypeScript

import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.feed.list({});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.

CLI

irvinebroque feed list

The SDK preserves status, headers, and the server envelope. A 304 has no fresh body. Errors retain structured problem details; ordinary error messages omit response details. Responses are limited to 16 MiB and requests time out after 30 seconds by default.

Work & ideas

Reading & watching

Out & about

Listening

List unified feed items

Request policy

Parameters

Request headers

Responses

200

304

400

406

429

503

Examples

curl

TypeScript

CLI