Feed API

The Feed API provides public, read-only access to published content. No authentication is required for public feeds — just make HTTP requests.

All responses include Access-Control-Allow-Origin: *, so you can call the API directly from browser JavaScript.

Base URL

https://your-org.flarebuilder.com/feed

Endpoints

GET /feed

Returns a paginated list of published content items as JSON, or an ICS calendar feed when format=ics is specified.

GET /feed/:channelName

Returns content from a specific channel. All channel feeds are unlisted and require a ?token= query parameter. Returns 401 if the token is missing or invalid.

GET /p/:id

Returns a single published content item by its UUID. For unlisted content, pass ?token= to authenticate.

Query Parameters

Parameter	Type	Default	Description
format	string	json	Response format: json or ics
limit	number	20	Items per page (max: 100)
cursor	string	—	Pagination cursor from previous response
tags	string	—	Filter by tag(s). Supports OR and AND logic (see Tag Filtering)
templates	string	—	Filter by template name(s), comma-separated OR: templates=event,announcement
ids	string	—	Filter to specific item IDs, comma-separated
user_id	string	—	Filter by author user ID(s), comma-separated
status	string	active	Content status: active, scheduled, or expired
sort	string	created	Sort order: created (newest first) or relevance (requires q)
q	string	—	Full-text search query. Requires a plan that includes full-text search
timezone	string	UTC	IANA timezone for interpreting date filter values (e.g. America/New_York)
publish_start	string	—	Filter: published on or after this datetime
publish_end	string	—	Filter: published on or before this datetime
event_start	string	—	Filter: event starts on or after this datetime
event_end	string	—	Filter: event starts on or before this datetime
expire_start	string	—	Filter: expires on or after this datetime
expire_end	string	—	Filter: expires on or before this datetime
geobox	string	—	Geographic bounding box filter (see Geo Filtering)

Date parameters accept ISO 8601 datetime strings (2025-06-15T14:30:00). When timezone is set, date values are interpreted in that timezone and converted to UTC for querying.

Tag Filtering

The tags parameter supports both OR and AND logic.

Expression	Meaning
tags=news	Items tagged news
tags=news,events	Items tagged news OR events
tags=[news,featured]	Items tagged news AND featured
tags=[news,featured],events	Items tagged (news AND featured) OR events

Limits: up to 5 OR groups, up to 5 tags per AND group.

OR filter

curl "https://your-org.flarebuilder.com/feed?tags=news,announcements"

AND filter

curl "https://your-org.flarebuilder.com/feed?tags=[news,featured]"

Mixed

curl "https://your-org.flarebuilder.com/feed?tags=[news,featured],events"

Filtering Examples

By Template

# Single template
curl "https://your-org.flarebuilder.com/feed?templates=event"

# Multiple templates (OR)
curl "https://your-org.flarebuilder.com/feed?templates=event,announcement"

By Date

# Events starting this week, in Eastern time
curl "https://your-org.flarebuilder.com/feed?event_start=2025-06-01T00:00:00&event_end=2025-06-07T23:59:59&timezone=America/New_York"

# Content published this year
curl "https://your-org.flarebuilder.com/feed?publish_start=2025-01-01&timezone=UTC"

By Status

# Scheduled content (future publish date)
curl "https://your-org.flarebuilder.com/feed?status=scheduled"

# Expired content
curl "https://your-org.flarebuilder.com/feed?status=expired"

Full-text Search

# Requires full-text search plan feature
curl "https://your-org.flarebuilder.com/feed?q=quarterly+report&sort=relevance"

Geographic Filtering

Use geobox to filter content with location data to a geographic bounding box.

# 2D bounding box: minLat,minLon,maxLat,maxLon
geobox=40.4,-74.3,40.9,-73.7

# 3D bounding box (includes altitude): minLat,minLon,minAlt,maxLat,maxLon,maxAlt
geobox=40.4,-74.3,0,40.9,-73.7,1000

Response Format

{
  "title": "Your Organization Feed",
  "description": "Optional organization description",
  "feed_url": "https://your-org.flarebuilder.com/feed",
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Article",
      "template_name": "article",
      "template_id": "tmpl-uuid",
      "tags": ["news", "featured"],
      "date_published": "2025-06-15T10:00:00.000Z",
      "date_expires": null,
      "date_created": "2025-06-14T08:00:00.000Z",
      "author": {
        "id": "user-uuid"
      },
      "permalink": "https://your-org.flarebuilder.com/p/550e8400-e29b-41d4-a716-446655440000",
      "sections": [
        {
          "id": "main",
          "label": "Main",
          "data": {
            "summary": "Brief description of the article",
            "body": "<p>Rich HTML content</p>"
          }
        }
      ]
    }
  ],
  "pagination": {
    "next": "https://your-org.flarebuilder.com/feed?cursor=eyJpZCI6Ii4uLiJ9&limit=20",
    "limit": 20,
    "has_more": true
  },
  "generator": {
    "name": "FlareBuilder",
    "url": "https://flarebuilder.com",
    "version": "2.0",
    "generated_at": "2025-06-15T12:00:00.000Z"
  }
}

Content Sections

Content fields are organized into sections as defined by the template. Each section includes an id, a human-readable label (from the template definition), and a data object containing the field values. The exact fields within each section depend on how the template was configured in FlareBuilder. Common field types include:

• summary — plain text summary
• body — rich HTML content (or ProseMirror JSON, depending on the template’s output_format setting — see Rich Text Output)
• date_event_start, date_event_end — event date/time fields
• location_geo — geographic coordinates { lat, lon, alt? }
• Custom fields defined in the template

Tip

Inspect a real response from your feed to discover the exact section IDs and field names for your templates.

Author Field

The author object always contains id. The name field is included only when the organization has enabled author attribution in their settings.

// Author attribution disabled (default)
"author": { "id": "user-uuid" }

// Author attribution enabled
"author": { "id": "user-uuid", "name": "Jane Smith" }

Pagination

The Feed API uses cursor-based keyset pagination for consistent, high-performance results regardless of dataset size.

1. Make your first request without a cursor
2. Check pagination.has_more in the response
3. If true, pass the cursor value from pagination.next URL as ?cursor= in your next request
4. Repeat until has_more is false

async function fetchAll(feedUrl) {
  const items = [];
  let url = feedUrl;

  while (url) {
    const res  = await fetch(url);
    const data = await res.json();
    items.push(...data.items);
    // pagination.next is a full ready-to-use URL (or null)
    url = data.pagination.has_more ? data.pagination.next : null;
  }

  return items;
}

Tip

Cursor-based pagination is O(log N) — unlike offset pagination, performance doesn’t degrade as you page deeper into results.

Caching

The Feed API implements a multi-layer caching strategy:

Layer	TTL	Description
Edge cache	15 minutes	Cloudflare CDN at 300+ locations
Browser cache	5 minutes	Cache-Control: max-age=300
Stale-while-revalidate	—	Serves stale content during cache refresh

Cache invalidation happens automatically when content is published, updated, or deleted in FlareBuilder.

Response Headers

Each response includes diagnostic headers:

Header	Description
X-Cache-Status	HIT, MISS, or STALE
X-Cache-Version	Cache version number (increments on invalidation)

ETags

Use ETags for efficient polling — the server returns 304 Not Modified when content hasn’t changed:

# First request — save the ETag
curl -i "https://your-org.flarebuilder.com/feed"
# Response includes: ETag: "abc123"

# Subsequent requests
curl -H "If-None-Match: abc123" "https://your-org.flarebuilder.com/feed"
# Returns 304 Not Modified if unchanged

ICS Calendar Feeds

Add ?format=ics to get a standards-compliant iCalendar file compatible with Google Calendar, Outlook, Apple Calendar, and any other .ics-capable application.

https://your-org.flarebuilder.com/feed?format=ics&templates=event

Note

ICS feeds must be enabled by the organization in their FlareBuilder settings. Requests to /feed?format=ics return 403 if the organization has not enabled this feature.

Channel Feeds

Unlisted channel feeds scope content to a specific channel and require a token for access.

https://your-org.flarebuilder.com/feed/channel-name?token=your-token

All standard query parameters work with channel feeds. The token is provided by the organization that manages the channel. Tokens expire based on the channel’s configuration.

Channel feeds are served with Cache-Control: private — they are not cached at the edge.

Accessing Unlisted Content by Permalink

A single unlisted content item can be retrieved via /p/:id by passing the channel token:

https://your-org.flarebuilder.com/p/550e8400-e29b-41d4-a716-446655440000?token=your-token

Full-Text Search

The q parameter enables full-text search. This feature is only available on plans that include full-text search.

curl "https://your-org.flarebuilder.com/feed?q=quarterly+report&sort=relevance"

When sort=relevance is used, results are ordered by relevance score rather than creation date. Using sort=relevance without a q parameter returns an error.

If your plan does not include full-text search, the API returns:

{
  "error": "Full-text search (q parameter) is not available on your current plan",
  "feature": "full_text_search",
  "upgrade_required": true
}

Error Responses

Status	Description
200	Success
304	Not Modified (ETag match)
400	Bad request (invalid parameters)
401	Missing or invalid channel token
403	Feature not enabled (ICS feed disabled, or plan limit for q)
404	Tenant or content not found
410	Organization account is deactivated (feed permanently unavailable)
500	Server error

Errors return JSON with an error field:

{
  "error": "Invalid timezone: Foo/Bar. Please use IANA timezone identifiers like 'America/New_York' or 'UTC'."
}