API Reference

Complete API reference for Helix News Feeds. All endpoints use JSON for request and response bodies.

Base URL

https://api.feeds.onhelix.ai

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for details.

News Feed Management

Create a Feed

Creates a new news feed to organize articles from multiple sources.

POST /feeds/news

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "name": "Technology News",
  "description": "Latest technology and startup news"
}

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Feed name. Minimum 1 character.
`description`	string	Yes	Feed description. Minimum 1 character.

Response

Status: 201 Created

{
  "success": true,
  "data": {
    "id": "feed_2aKj39dkD",
    "name": "Technology News",
    "description": "Latest technology and startup news",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Response object:

Field	Type	Description
`id`	string	Unique feed identifier. Use this when adding sources or retrieving items.
`name`	string	Feed name
`description`	string	Feed description
`createdAt`	string (ISO 8601)	When the feed was created
`updatedAt`	string (ISO 8601)	Last time the feed was modified

Example

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

List Feeds

Retrieves all news feeds.

GET /feeds/news

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "feed_2aKj39dkD",
      "name": "Technology News",
      "description": "Latest technology and startup news",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "feed_9xLm47qwP",
      "name": "Business News",
      "description": "Business and finance updates",
      "createdAt": "2024-01-14T15:20:00.000Z",
      "updatedAt": "2024-01-14T15:20:00.000Z"
    }
  ]
}

Returns an array of feed objects sorted by creation date (newest first).

Example

curl https://api.feeds.onhelix.ai/feeds/news \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a Feed

Retrieves details for a specific feed.

GET /feeds/news/{feedId}

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier returned when creating the feed

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "feed_2aKj39dkD",
    "name": "Technology News",
    "description": "Latest technology and startup news",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Example

curl https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

404: Feed not found

Update a Feed

Updates a feed's name, description, or enabled status.

PATCH /feeds/news/{feedId}

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body (all fields optional):

{
  "name": "Tech & Startup News",
  "description": "Updated description",
  "enabled": true
}

Parameters:

Name	Type	Required	Description
`name`	string	No	Updated feed name
`description`	string	No	Updated feed description
`enabled`	boolean	No	Enable or disable the feed. When disabled, all sources stop monitoring.

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "feed_2aKj39dkD",
    "name": "Tech & Startup News",
    "description": "Updated description",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T14:25:00.000Z"
  }
}

The updatedAt field reflects the modification time.

Example

curl -X PATCH https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech & Startup News",
    "enabled": true
  }'

Delete a Feed

Permanently deletes a feed and all its sources. This does not delete the underlying articles, only the feed configuration.

DELETE /feeds/news/{feedId}

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true
}

Warning: This action is permanent and cannot be undone.

Example

curl -X DELETE https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Feed Items

Retrieves articles from a feed with optional filtering and pagination.

GET /feeds/news/{feedId}/items

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier

Query parameters:

Name	Type	Default	Description
`limit`	integer	50	Number of items to return. Range: 1-100.
`offset`	integer	0	Number of items to skip. Use for pagination.
`since`	string (ISO 8601)	-	Only items created after this date. Example: `2024-01-15T00:00:00Z`
`until`	string (ISO 8601)	-	Only items created before this date. Example: `2024-01-20T23:59:59Z`

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_3bNm58fwQ",
        "newsPageId": "page_7xQr92jkL",
        "type": "site",
        "data": {
          "sitePageId": "550e8400-e29b-41d4-a716-446655440003",
          "sitePageVersionId": "550e8400-e29b-41d4-a716-446655440004",
          "url": "https://techcrunch.com/2024/01/15/ai-startup-funding",
          "title": "AI Startup Raises $100M Series B",
          "description": "The company plans to expand its enterprise AI platform..."
        },
        "createdAt": "2024-01-15T12:00:00.000Z",
        "updatedAt": "2024-01-15T12:00:00.000Z"
      }
    ],
    "total": 156,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  }
}

Feed item object:

Field	Type	Description
`id`	string	Unique item identifier
`newsPageId`	string	Internal reference to the news page
`type`	string	Source type: `site` or `instagram`
`data`	object	Item data. Structure varies by type.
`data.url`	string	Article URL
`data.title`	string	Article headline (may be null if unavailable)
`data.description`	string	Article summary (may be null if unavailable)
`createdAt`	string (ISO 8601)	When the item was added to the feed
`updatedAt`	string (ISO 8601)	Last update time

Pagination object:

Field	Type	Description
`limit`	integer	Items per page (as requested)
`offset`	integer	Current offset (as requested)
`hasMore`	boolean	Whether more items are available. If `true`, increment `offset` by `limit` to get the next page.

Examples

Basic request:

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

Date filtering:

# Get articles from 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_2aKj39dkD/items?since=$YESTERDAY" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination:

# Page 1
curl "https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/items?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Page 2
curl "https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/items?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Page 3
curl "https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/items?limit=20&offset=40" \
  -H "Authorization: Bearer YOUR_API_KEY"

Date range:

curl "https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/items?since=2024-01-15T00:00:00Z&until=2024-01-20T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Source Management

Add a Source

Adds a website, sitemap, or index page as a source for a feed. The source immediately begins monitoring for new content.

Important: When you add a source, Helix automatically initiates a 14-day backfill to populate your feed with recent articles.

POST /feeds/news/{feedId}/sources

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body (varies by source type):

Website Source

Monitors all content from a domain.

{
  "sourceType": "site",
  "domain": "techcrunch.com"
}

Parameters:

Name	Type	Required	Description
`sourceType`	string	Yes	Must be `"site"`
`domain`	string	Yes	Domain name without protocol (e.g., `example.com`, not `https://example.com`)

What happens:

Helix creates a site record (or reuses existing)
Begins crawling the domain to discover articles
Starts 14-day backfill
Monitors for new content continuously

Sitemap Source

Monitors a specific XML sitemap.

{
  "sourceType": "sitemap",
  "url": "https://techcrunch.com/news-sitemap.xml",
  "siteId": "site_5dRu71lpS"
}

Parameters:

Name	Type	Required	Description
`sourceType`	string	Yes	Must be `"sitemap"`
`url`	string	Yes	Full URL to the sitemap. Must be publicly accessible.
`siteId`	string	Yes	Site identifier. Obtain by first creating a `site` source (use the returned `sourceId`).

Getting a siteId: Create a site source first. The response includes a sourceId field—use this value as the siteId for sitemap and index page sources.

# Step 1: Create a site source
curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -d '{"sourceType": "site", "domain": "example.com"}'
# Response includes: "sourceId": "site_5dRu71lpS"

# Step 2: Use that sourceId as siteId for sitemap
curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -d '{
    "sourceType": "sitemap",
    "url": "https://example.com/sitemap.xml",
    "siteId": "site_5dRu71lpS"
  }'

Index Page Source

Monitors a page that lists articles (e.g., category pages).

{
  "sourceType": "siteIndexPage",
  "url": "https://techcrunch.com/category/artificial-intelligence/",
  "siteId": "site_5dRu71lpS"
}

Parameters:

Name	Type	Required	Description
`sourceType`	string	Yes	Must be `"siteIndexPage"`
`url`	string	Yes	Full URL to the index page.
`siteId`	string	Yes	Site identifier (same as sitemap sources).

What it monitors: The page at the URL is regularly checked for new article links. When new links appear, their content is extracted and added to your feed.

Response

Status: 201 Created

{
  "success": true,
  "data": {
    "id": "src_6eVx82nqT",
    "newsFeedId": "feed_2aKj39dkD",
    "sourceType": "site",
    "sourceId": "site_5dRu71lpS",
    "createdAt": "2024-01-15T10:45:00.000Z",
    "sourceDetails": {
      "sourceType": "site",
      "domain": "techcrunch.com"
    }
  }
}

Response object:

Field	Type	Description
`id`	string	Unique source identifier. Use when updating or deleting.
`newsFeedId`	string	Feed this source belongs to
`sourceType`	string	Type: `site`, `sitemap`, or `siteIndexPage`
`sourceId`	string	Important: For `site` sources, use this value as `siteId` when creating sitemap/index page sources.
`createdAt`	string (ISO 8601)	When the source was added
`sourceDetails`	object	Echo of the source configuration

Examples

Website source:

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

Sitemap source:

curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "sitemap",
    "url": "https://techcrunch.com/news-sitemap.xml",
    "siteId": "site_5dRu71lpS"
  }'

Index page source:

curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "siteIndexPage",
    "url": "https://techcrunch.com/category/startups/",
    "siteId": "site_5dRu71lpS"
  }'

Errors

404: Feed not found
409: Source already exists for this feed

List Sources

Retrieves all sources configured for a feed.

GET /feeds/news/{feedId}/sources

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "src_6eVx82nqT",
      "newsFeedId": "feed_2aKj39dkD",
      "sourceType": "site",
      "sourceId": "site_5dRu71lpS",
      "createdAt": "2024-01-15T10:45:00.000Z"
    },
    {
      "id": "src_9hZy15ruW",
      "newsFeedId": "feed_2aKj39dkD",
      "sourceType": "sitemap",
      "sourceId": "stm_3fTw46kpM",
      "createdAt": "2024-01-15T11:20:00.000Z"
    }
  ]
}

Returns an array of source objects sorted by creation date (newest first).

Example

curl https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a Source

Enables or disables monitoring for a source without deleting it.

PATCH /feeds/news/{feedId}/sources/{sourceId}

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier
`sourceId`	string	Source identifier (from source `id` field, not `sourceId` field)

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "enabled": false
}

Parameters:

Name	Type	Required	Description
`enabled`	boolean	Yes	`true` to enable monitoring, `false` to disable

Behavior:

When disabled: Stops monitoring for new articles. Existing feed items remain.
When re-enabled: Resumes monitoring but does not backfill articles published while disabled.

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "src_6eVx82nqT",
    "newsFeedId": "feed_2aKj39dkD",
    "sourceType": "site",
    "sourceId": "site_5dRu71lpS",
    "createdAt": "2024-01-15T10:45:00.000Z"
  }
}

Example

# Disable a source
curl -X PATCH https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources/src_6eVx82nqT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Re-enable later
curl -X PATCH https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources/src_6eVx82nqT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Delete a Source

Permanently removes a source from a feed. Articles already in the feed remain.

DELETE /feeds/news/{feedId}/sources/{sourceId}

Request

Path parameters:

Name	Type	Description
`feedId`	string	Feed identifier
`sourceId`	string	Source identifier

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true
}

Warning: This action is permanent. To temporarily stop monitoring, use the update endpoint instead.

Example

curl -X DELETE https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources/src_6eVx82nqT \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All endpoints use consistent error responses.

400 Bad Request

Invalid request parameters or body.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required"
  }
}

Common causes:

Missing required fields
Invalid data types
Values outside allowed ranges

401 Unauthorized

Missing or invalid API key.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Common causes:

Missing Authorization header
Incorrect header format
Invalid API key

404 Not Found

Resource doesn't exist.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "News feed not found",
    "resource": "News feed",
    "id": "feed_2aKj39dkD"
  }
}

Common causes:

Incorrect ID
Resource was deleted

409 Conflict

Resource already exists.

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "News feed source already exists"
  }
}

Common causes:

Attempting to add a duplicate source

500 Internal Server Error

Unexpected server error.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

If this persists: Retry the request

Best Practices

Use the siteId Pattern

When adding sitemaps or index pages for a domain:

Create a site source first
Save the returned sourceId
Use that as siteId for related sources

# Create site source
RESPONSE=$(curl -s -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -d '{"sourceType": "site", "domain": "example.com"}')

SITE_ID=$(echo $RESPONSE | jq -r '.data.sourceId')

# Now create sitemap using that siteId
curl -X POST https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/sources \
  -d "{
    \"sourceType\": \"sitemap\",
    \"url\": \"https://example.com/sitemap.xml\",
    \"siteId\": \"$SITE_ID\"
  }"

Paginate Large Result Sets

Always use pagination for feeds with many articles:

async function getAllFeedItems(feedId) {
  const allItems = [];
  let offset = 0;
  const limit = 100; // Max allowed
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.feeds.onhelix.ai/feeds/news/${feedId}/items?limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );

    const result = await response.json();
    allItems.push(...result.data.items);

    hasMore = result.data.pagination.hasMore;
    offset += limit;
  }

  return allItems;
}

Use Date Filters

Filter by date range to reduce response size:

# Get today's articles
TODAY=$(date -u +%Y-%m-%dT00:00:00Z)
curl "https://api.feeds.onhelix.ai/feeds/news/feed_2aKj39dkD/items?since=$TODAY" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Reference

Base URL​

Authentication​

News Feed Management​

Create a Feed​

Request​

Response​

Example​

List Feeds​

Request​

Response​

Example​

Get a Feed​

Request​

Response​

Example​

Errors​

Update a Feed​

Request​

Response​

Example​

Delete a Feed​

Request​

Response​

Example​

Get Feed Items​

Request​

Response​

Examples​

Source Management​

Add a Source​

Request​

Website Source​

Sitemap Source​

Index Page Source​

Response​

Examples​

Errors​

List Sources​

Request​

Response​

Example​

Update a Source​

Request​

Response​

Example​

Delete a Source​

Request​

Response​

Example​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

409 Conflict​

500 Internal Server Error​

Best Practices​

Use the siteId Pattern​

Paginate Large Result Sets​

Use Date Filters​

Base URL

Authentication

News Feed Management

Create a Feed

Request

Response

Example

List Feeds

Request

Response

Example

Get a Feed

Request

Response

Example

Errors

Update a Feed

Request

Response

Example

Delete a Feed

Request

Response

Example

Get Feed Items

Request

Response

Examples

Source Management

Add a Source

Request

Website Source

Sitemap Source

Index Page Source

Response

Examples

Errors

List Sources

Request

Response

Example

Update a Source

Request

Response

Example

Delete a Source

Request

Response

Example

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict

500 Internal Server Error

Best Practices

Use the siteId Pattern

Paginate Large Result Sets

Use Date Filters