Skip to main content
Skip to main content
Helix
Book a briefing →

Quickstart

Build a news feed end to end through the API: create it, add the websites its articles come from, give it an area, decide what it carries, enable it and read its articles.

Prerequisites​

Before you begin, you'll need:

  • A Helix API key (see Authentication)
  • A command-line terminal or API client

Step 1: Create a News Feed​

Create a feed to organize articles from your sources.

curl -X POST https://api.feeds.onhelix.ai/feeds/news \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local News",
    "description": "Local news coverage"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57",
    "name": "Local News",
    "description": "Local news coverage",
    "organizationId": "660e8400-e29b-41d4-a716-446655440001",
    "enabled": false,
    "enabledSource": "system",
    "enabledReason": null,
    "config": { "version": 1 },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Save the id value—you'll need it in the next steps. A new news feed starts disabled and with no filters. Its images stay available for 30 days after an article enters the feed; set config.media.retentionDaysAfterAdded (1 to 365) to change that.

Step 2: Add a Website​

Add a website as a source for your feed. The whole site is added, whatever the path. A disabled feed takes no articles in: the site's articles from the past 14 days reach the feed when you enable it in Step 5.

curl -X POST https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "site",
    "url": "https://www.macombdaily.com/news/local/"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "9b2f6c1e-4d3a-4e8b-9c7d-2a1b0f3e5d64",
    "type": "site",
    "identity": {
      "domain": "www.macombdaily.com"
    },
    "enabled": true,
    "addedAt": "2026-10-28T14:05:00.000Z"
  }
}

identity.domain is the site as we crawl it: a site we already crawl under the same host with or without www. is reused. Sitemaps, index pages and social accounts are added by our team: contact support. See Sources.

Step 3: Create an Area (Optional)​

To keep the feed to a part of the world, create an area as an area match processor. Make it cover the places your sources write about: here, Macomb County for the Macomb Daily.

curl -X POST https://api.feeds.onhelix.ai/processors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "area_match",
    "name": "Macomb County",
    "definition": {
      "area": {
        "name": "Macomb County",
        "places": [{ "name": "Macomb County, Michigan" }]
      }
    }
  }'

A place name without a level is a county (district); a name that is not exactly one place is refused with 422 AREA_PLACES_UNRESOLVED, listing candidates. Save the processor's id. An area match counts a story only when a place it is about lies inside the area; to also take in stories about the region as a whole, create an area_relevance processor with the same places and pass it as areaRelevance below.

Step 4: Decide What the Feed Carries​

Add the Standard news set of opt-in filters: it includes editorial news and opinion pieces and excludes sponsored content and self-promotion. With areaMatch, it includes only articles in the area:

curl -X POST https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/filter-sets/standard_news \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "with": { "areaMatch": "5c0e8f9a-3b1d-4f6e-9a2c-7d4b1e0f8a63" } }'

The response lists the filters added and any skipped because the feed already had them. Send {} instead to include news from anywhere.

You can add your own filters beside them. An article is in the feed when no exclude matches and at least one include does, so your own include widens the feed: an include on news_content_type's editorial_news.significance >= 7, for example, would let in strong news stories from outside the area too. To narrow the feed, add an exclude.

Step 5: Enable the Feed​

curl -X PATCH https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Enabling needs at least one include filter: the set added one. Enabling adds the articles your sites brought in during the past 14 days that pass the feed's filters, once per site.

Step 6: Retrieve Feed Items​

After a few minutes, fetch articles from your feed:

curl "https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/items?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (the same fields for every source type):

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "3f6c1d52-7a0e-4b8e-9d1c-5a2b8e4f6a10",
        "newsPageId": "9b2e7c44-1d3a-4f65-8a7b-0c5d2e9f1b33",
        "addedToFeedAt": "2026-10-20T14:03:00.000Z",
        "updatedAt": "2026-10-20T14:03:00.000Z",
        "title": "Sterling Heights approves library expansion",
        "description": "The city council voted 6-1 on Monday to fund a 12,000-square-foot addition to the Sterling Heights Public Library.",
        "url": "https://www.macombdaily.com/2026/10/19/sterling-heights-approves-library-expansion/",
        "publishedAt": "2026-10-20T09:15:00.000Z",
        "publisher": {
          "platform": "web",
          "name": "Macomb Daily",
          "domain": "macombdaily.com"
        },
        "author": "Jane Smith",
        "original": {
          "publisher": {
            "platform": "web",
            "name": "Detroit Free Press",
            "domain": "freep.com"
          },
          "url": "https://www.freep.com/story/news/local/michigan/macomb/2026/10/19/sterling-heights-library-expansion/1234567890/",
          "publishedAt": "2026-10-19T11:30:00.000Z"
        },
        "about": {
          "places": [
            {
              "name": "Sterling Heights",
              "level": "place",
              "displayText": "Sterling Heights, MI",
              "geo": {
                "lat": 42.57,
                "lng": -83.025,
                "bbox": [-83.08, 42.52, -82.97, 42.62]
              },
              "city": "Sterling Heights",
              "district": "Macomb County",
              "region": "Michigan",
              "country": "United States"
            },
            {
              "name": "Macomb County",
              "level": "district",
              "displayText": "Macomb County, MI",
              "geo": {
                "lat": 42.65,
                "lng": -82.9,
                "bbox": [-83.1, 42.5, -82.7, 42.8]
              },
              "district": "Macomb County",
              "region": "Michigan",
              "country": "United States"
            }
          ]
        },
        "media": {
          "cover": {
            "url": "https://example.r2.cloudflarestorage.com/media/2026-10/library-expansion.jpg?X-Amz-Signature=...",
            "expiresAt": "2026-10-28T12:00:00.000Z",
            "usage": "display_with_attribution",
            "kind": "article_image",
            "source": {
              "imageUrl": "https://www.macombdaily.com/wp-content/uploads/2026/10/library-expansion.jpg",
              "pageUrl": "https://www.macombdaily.com/2026/10/19/sterling-heights-approves-library-expansion/",
              "publisher": {
                "platform": "web",
                "name": "Macomb Daily",
                "domain": "macombdaily.com"
              },
              "credit": "Jane Smith / The Macomb Daily"
            },
            "width": 1200,
            "height": 800
          },
          "images": [
            {
              "url": "https://example.r2.cloudflarestorage.com/media/2026-10/library-expansion.jpg?X-Amz-Signature=...",
              "expiresAt": "2026-10-28T12:00:00.000Z",
              "usage": "display_with_attribution",
              "kind": "article_image",
              "source": {
                "imageUrl": "https://www.macombdaily.com/wp-content/uploads/2026/10/library-expansion.jpg",
                "pageUrl": "https://www.macombdaily.com/2026/10/19/sterling-heights-approves-library-expansion/",
                "publisher": {
                  "platform": "web",
                  "name": "Macomb Daily",
                  "domain": "macombdaily.com"
                },
                "credit": "Jane Smith / The Macomb Daily"
              },
              "width": 1200,
              "height": 800
            }
          ]
        }
      }
    ],
    "total": 1,
    "pagination": {
      "limit": 10,
      "offset": 0,
      "hasMore": false
    }
  }
}

Optional fields are omitted (not nulled) when missing: check for key presence ('title' in item) rather than for null. publisher says who published the item, about.places lists the places it is about, and media holds its images. Image links are temporary: do not store them. See the API reference for every field.

Next Steps​

Now that you have a working feed, you can:

  • Add more websites: Monitor several sites in one feed
  • Tune what the feed carries: See Filters and Processors
  • Set up event delivery: Register a destination and subscribe it to this feed to get notified when new articles are added, instead of polling
  • Filter by date: Use addedSince and addedUntil (or publishedSince and publishedUntil) to query specific time ranges
  • Paginate results: Use limit and offset to retrieve large result sets

Common Patterns​

Monitor Multiple Sources​

# Add another source to the same feed
curl -X POST https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "site",
    "url": "https://www.wired.com"
  }'

Filter by Date Range​

# Get articles from the last 24 hours
YESTERDAY=$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)
curl "https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/items?addedSince=$YESTERDAY&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginate Through Results​

# Get first page
curl "https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/items?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get second page
curl "https://api.feeds.onhelix.ai/feeds/news/7c1e5a90-3b2d-4f68-9a14-6d8e0b2c4f57/items?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"