API Reference

Complete reference for the FlareBuilder Feed API

Overview

The FlareBuilder Feed API provides read-only access to your organization's published content. It's a RESTful JSON API that requires no authentication and is globally distributed on Cloudflare's edge network for optimal performance.

No authentication required - Public read access to published content
RESTful JSON API - Simple HTTP GET requests
Globally distributed - Served from Cloudflare's edge network
CORS enabled - Call from any domain
ETag support - Efficient conditional requests

Endpoint

GET https://feed.flarebuilder.com/{tenant-slug}

Replace {tenant-slug} with your organization's unique slug. You can find your slug in your FlareBuilder dashboard.

Core Parameters

format

Property	Value
Type	String
Default	`json`
Valid Values	`json`, `ics`
Description	Output format for the feed. Use `ics` for calendar applications.

Note: The ICS format must be explicitly enabled in your tenant settings. Invalid format values default to json rather than returning an error.

# JSON feed (default)
curl https://feed.flarebuilder.com/your-org

# ICS calendar feed
curl https://feed.flarebuilder.com/your-org?format=ics

timezone

Property	Value
Type	String (IANA timezone identifier)
Default	`UTC`
Examples	`America/New_York`, `Europe/London`, `Asia/Tokyo`
Description	Timezone for interpreting date filter parameters. Date range filters are interpreted in this timezone, then converted to UTC for database queries.

# Fetch events in New York timezone
curl "https://feed.flarebuilder.com/your-org?timezone=America/New_York&event_start=2025-06-01T00:00:00"

Filtering Parameters

ids

Property	Value
Type	Comma-separated string
Default	Empty (all items)
Logic	OR (returns items matching ANY of the IDs)
Description	Filter by specific content item IDs

curl "https://feed.flarebuilder.com/your-org?ids=abc123,def456,ghi789"

Property	Value
Type	String with AND/OR syntax (case-insensitive)
Default	Empty (all items)
Syntax	Comma-separated for OR: `tags=foo,bar` Brackets for AND: `tags=[foo,bar]` Mix for complex logic: `tags=[foo,bar],baz`
Logic	OR between groups, AND within brackets Max 5 groups, 5 tags per AND group
Description	Filter by tag names with flexible AND/OR logic. Tag matching is case-insensitive. Items can have multiple tags, enabling complex boolean queries.

types

Property	Value
Type	Comma-separated string (case-insensitive)
Default	Empty (all types)
Syntax	Comma-separated only: `types=event,announcement` Note: AND syntax (brackets) not supported - items have a single template
Logic	OR only (returns items matching ANY type)
Description	Filter by template/content type names. Type matching is case-insensitive. Each item has exactly one type, so only OR logic applies.

curl "https://feed.flarebuilder.com/your-org?types=Event,Article,Announcement"

user_id

Property	Value
Type	Comma-separated string
Default	Empty (all authors)
Logic	OR (returns items by ANY of the specified authors)
Description	Filter by author user IDs

curl "https://feed.flarebuilder.com/your-org?user_id=user-uuid-1,user-uuid-2"

status

Property	Value
Type	String
Default	`active`
Valid Values	`active`, `scheduled`, `expired`
Description	Filter by content publication status: • `active`: Published and not expired • `scheduled`: Publish date in future • `expired`: Has expiration date in past

# Get upcoming scheduled content
curl "https://feed.flarebuilder.com/your-org?status=scheduled"

Date Range Filters

All date filters accept ISO 8601 format (YYYY-MM-DDTHH:MM:SS) and are interpreted in the timezone specified by the timezone parameter.

Published Date Range

Parameter	Description
publish_start	Filter items published on or after this date
publish_end	Filter items published on or before this date

# Content published in 2025
curl "https://feed.flarebuilder.com/your-org?publish_start=2025-01-01T00:00:00&publish_end=2025-12-31T23:59:59"

Event Date Range

Parameter	Description
event_start	Filter items with event_start_date on or after this date (only applies to content with event dates)
event_end	Filter items with event_end_date on or before this date (only applies to content with event dates)

# Events in June 2025 (Eastern Time)
curl "https://feed.flarebuilder.com/your-org?types=Event&timezone=America/New_York&event_start=2025-06-01T00:00:00&event_end=2025-06-30T23:59:59"

Expiration Date Range

Parameter	Description
expire_start	Filter items with expiration date on or after this date
expire_end	Filter items with expiration date on or before this date

Pagination & Sorting

limit

Property	Value
Type	Integer
Default	`10`
Description	Maximum number of items to return

offset

Property	Value
Type	Integer
Default	`0`
Description	Number of items to skip (for pagination)

# Get items 21-40 (page 2 with limit=20)
curl "https://feed.flarebuilder.com/your-org?limit=20&offset=20"

sort_by

Property	Value
Type	Comma-separated string
Default	`event,publish`
Valid Values	`event`, `publish`, `created`
Description	Fields to sort by (in order of priority): • `event`: Sort by event_start_date (items without events sorted last) • `publish`: Sort by date_published • `created`: Sort by date_created

sort_order

Property	Value
Type	Comma-separated string
Default	`asc,desc`
Valid Values	`asc`, `desc` (case-insensitive)
Description	Sort order for each field in `sort_by`. If fewer orders than fields, missing orders default to `asc`.

# Sort by newest published first, then by creation date
curl "https://feed.flarebuilder.com/your-org?sort_by=publish,created&sort_order=desc,desc"

Response Format

The API returns a JSON object with the following structure:

{
  "title": "Your Organization Feed",
  "description": "Organization description (if set)",
  "feed_url": "https://feed.flarebuilder.com/your-org?...",
  "items": [
    {
      "id": "content-uuid",
      "title": "Sample Event",
      "tags": ["community", "event"],
      "type": "Event",
      "date_published": "2025-06-05T10:30:00Z",
      "date_expires": null,
      "date_created": "2025-06-01T08:00:00Z",
      "author": {
        "id": "user-uuid",
        "name": "John Doe"
      },
      "permalink": "https://tenant.flarebuilder.com/p/content-uuid",
      "sections": {
        "core": {
          "description": "Event description",
          "content_json": {...}
        },
        "event": {
          "event_start": "2025-06-10T18:00:00Z",
          "event_end": "2025-06-10T21:00:00Z",
          "location": "123 Main St"
        },
        "template": {
          "custom_field_1": "value"
        }
      }
    }
  ],
  "pagination": {
    "next": "https://feed.flarebuilder.com/your-org?offset=10&limit=10",
    "prev": null,
    "limit": 10,
    "offset": 0,
    "total": 10
  },
  "generator": {
    "name": "FlareBuilder",
    "url": "https://flarebuilder.com",
    "version": "1.0",
    "generated_at": "2025-06-05T12:00:00Z"
  }
}

Field Descriptions

Field	Description
id	Unique content item identifier
title	Content item title
tags	Array of tag names
type	Template/content type name
date_published	ISO 8601 timestamp (UTC) when content was published
date_expires	ISO 8601 timestamp (UTC) when content expires, or null
author	Author object with id and name (name only included if enabled in settings)
permalink	Direct link to view content
sections	Content fields organized by section (varies by template)

Caching & ETags

The Feed API supports efficient caching through ETags and Cache-Control headers. All responses include an ETag header that can be used for conditional requests.

Conditional Requests

# Initial request
curl -i "https://feed.flarebuilder.com/your-org"
# Returns: ETag: "feed-2025-06-05T10:30:00Z-a7f9c2d1"

# Subsequent request with If-None-Match
curl -i -H 'If-None-Match: "feed-2025-06-05T10:30:00Z-a7f9c2d1"' \
  "https://feed.flarebuilder.com/your-org"
# Returns: 304 Not Modified (if content unchanged)

Cache Headers

Header	Value
ETag	Unique identifier for this specific version of the feed
Cache-Control	`public, max-age=300, s-maxage=1800, stale-while-revalidate=60`
X-Cache	`HIT` or `MISS` - indicates whether response was served from cache

Performance Tip: The feed uses coarse-grained caching with in-memory filtering. Cache hit ratio is typically >90%, resulting in <5ms response times.

Example Queries

Basic Feed

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

Events in Specific Timezone

curl "https://feed.flarebuilder.com/your-org?types=Event&timezone=America/New_York"

Upcoming Events with Tags

curl "https://feed.flarebuilder.com/your-org?types=Event&tags=community,fundraiser&event_start=2025-06-01T00:00:00&status=active"

ICS Calendar Feed

curl "https://feed.flarebuilder.com/your-org?format=ics&types=Event"

Paginated Feed with Custom Sorting

curl "https://feed.flarebuilder.com/your-org?limit=20&offset=40&sort_by=publish,created&sort_order=desc,desc"

Filter by Author and Date Range

curl "https://feed.flarebuilder.com/your-org?user_id=user-uuid&publish_start=2025-01-01T00:00:00&publish_end=2025-12-31T23:59:59"

Multi-Type Feed with Tag Filtering

curl "https://feed.flarebuilder.com/your-org?types=Event,Article,Announcement&tags=important&limit=50"

Tag AND Filtering

Find items that have ALL specified tags:

# Items tagged BOTH "urgent" AND "security"
curl "https://feed.flarebuilder.com/your-org?tags=%5Burgent,security%5D"

Complex Tag Logic

Combine AND/OR logic for advanced filtering:

# Items with (urgent AND security) OR public
curl "https://feed.flarebuilder.com/your-org?tags=%5Burgent,security%5D,public"

# Events that are (community AND fundraiser) OR educational
curl "https://feed.flarebuilder.com/your-org?types=Event&tags=%5Bcommunity,fundraiser%5D,educational"

# Multiple AND groups: (breaking AND news) OR (sports AND highlight)
curl "https://feed.flarebuilder.com/your-org?tags=%5Bbreaking,news%5D,%5Bsports,highlight%5D"

Error Responses

Code	Description
`200`	Success - Content returned
`304`	Not Modified - Content unchanged (conditional request)
`400`	Bad Request - Invalid timezone, status, tag syntax, or type AND query
`403`	Forbidden - ICS feed disabled for this tenant
`404`	Not Found - Tenant not found
`410`	Gone - Tenant deactivated (permanent)
`500`	Internal Server Error - Feed generation failed

Example Error Responses

Invalid Tag Syntax

{
  "error": "Invalid tag syntax: Unmatched opening bracket \"[\" at position 0",
  "items": [],
  "pagination": { "total": 0, "limit": 10, "offset": 0, "next": null, "prev": null }
}

Type AND Not Supported

{
  "error": "AND logic not supported for types. Items have a single template. Use comma for OR: types=event,announcement",
  "items": [],
  "pagination": { "total": 0, "limit": 10, "offset": 0, "next": null, "prev": null }
}

Too Many Tag Groups

{
  "error": "Invalid tag syntax: Maximum 5 tag groups allowed (found 6)",
  "items": [],
  "pagination": { "total": 0, "limit": 10, "offset": 0, "next": null, "prev": null }
}

Performance Characteristics

Metric	Value
Cache Hit Response Time	~5-10ms
Cache Miss Response Time	~50-100ms
In-Memory Filtering	<1ms for 1000 items
Cache Hit Ratio	>90%
JSON Feed Cache TTL	15 minutes (900s)
ICS Feed Cache TTL	1 hour (3600s)
Maximum Items Cached	1000 items per cache key

Architecture Note: FlareBuilder uses coarse-grained caching with in-memory filtering. This means broad datasets are cached (by type, format, status), and filters like tags, dates, and pagination are applied in worker memory. This approach maximizes cache reuse and minimizes database queries.

API Reference

API Reference

Overview

Endpoint

Core Parameters

format

timezone

Filtering Parameters

ids

tags

Tag Query Examples

types

user_id

status

Date Range Filters

Published Date Range

Event Date Range

Expiration Date Range

Pagination & Sorting

limit

offset

sort_by

sort_order

Response Format

Field Descriptions

Caching & ETags

Conditional Requests

Cache Headers

Example Queries

Basic Feed

Events in Specific Timezone

Upcoming Events with Tags

ICS Calendar Feed

Paginated Feed with Custom Sorting

Filter by Author and Date Range

Multi-Type Feed with Tag Filtering

Tag AND Filtering

Complex Tag Logic

Error Responses

Example Error Responses

Invalid Tag Syntax

Type AND Not Supported

Too Many Tag Groups

Performance Characteristics