Skip to main content

Quickstart

Get started with Helix News Feeds in under 5 minutes. This guide walks you through creating your first feed and retrieving articles.

Prerequisites​

Before you begin, you'll need:

  • A Helix API key (see API Reference)
  • 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": "Tech News",
    "description": "Technology and startup coverage"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "feed_abc123",
    "name": "Tech News",
    "description": "Technology and startup coverage",
    "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 step.

Step 2: Add a Source​

Add a website as a source for your feed. This tells Helix which site to monitor for new articles.

curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_abc123/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "site",
    "domain": "techcrunch.com"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "source_xyz789",
    "newsFeedId": "feed_abc123",
    "sourceType": "site",
    "sourceId": "site_def456",
    "createdAt": "2024-01-15T10:45:00.000Z"
  }
}

What happens next?

  • Helix automatically begins a 14-day backfill to populate your feed with recent articles
  • The source is monitored for new content

Step 3: Retrieve Feed Items​

After a few minutes, fetch articles from your feed:

curl "https://api.feeds.onhelix.ai/feeds/news/feed_abc123/items?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_111",
        "newsPageId": "page_222",
        "type": "site",
        "data": {
          "url": "https://techcrunch.com/2024/01/15/ai-startup-raises-100m",
          "title": "AI Startup Raises $100M in Series B",
          "description": "Company plans to expand operations..."
        },
        "createdAt": "2024-01-15T12:00:00.000Z",
        "updatedAt": "2024-01-15T12:00:00.000Z"
      }
    ],
    "total": 156,
    "pagination": {
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}

Next Steps​

Now that you have a working feed, you can:

  • Add more sources: Monitor multiple sites, sitemaps, or index pages
  • Set up webhooks: Get notified when new articles are added
  • Filter by date: Use since and until parameters 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/feed_abc123/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "site",
    "domain": "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/feed_abc123/items?since=$YESTERDAY&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginate Through Results​

# Get first page
curl "https://api.feeds.onhelix.ai/feeds/news/feed_abc123/items?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get second page
curl "https://api.feeds.onhelix.ai/feeds/news/feed_abc123/items?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"