# Syncing & Refresh

Weavestream keeps your data up to date by periodically syncing with your API sources and RSS feeds. You can also trigger syncs manually at any time.

# Manual Sync

# Sync Everything

Click the Sync All button in the toolbar or press Cmd+R to refresh all sources and feeds at once. A progress indicator shows while syncing is in progress.

# Sync a Single Source or Category

Hover over a source or RSS category in the sidebar, click the ... menu, and choose Sync Now. This refreshes only the endpoints or feeds within that source.

# Sync a Single Endpoint or Feed

Right-click an individual endpoint or feed in the sidebar and choose Sync Endpoint or Sync Feed. This is useful when you want to refresh one specific data stream without waiting for everything else.

# Automatic Refresh

Each source and RSS category has a configurable refresh interval. You set this when creating the source (in the Customize step) or by editing it later.

Available intervals:

Weavestream runs background syncs at your chosen interval while the app is open. The last sync time is displayed in the interface so you always know how fresh your data is.

# Retention Modes

Each endpoint and RSS feed has a retention mode that controls what happens to existing items when new data comes in. You configure this when adding or editing an endpoint or feed.

# Keep All

The default mode. Every item Weavestream has ever fetched is kept in the database. New items are added, but nothing is removed.

Use this when:

• You want a complete historical record
• You're tracking items over time (e.g., tickets, transactions)
• You want to search or analyze past data

# Delete on Sync

Items that are no longer present in the latest API response are deleted from Weavestream. Only the current set of items remains.

Use this when:

• You only care about the current state (e.g., active alerts, open tickets)
• You want to keep your item list clean and current
• The API represents a live snapshot rather than a history

# Archive on Sync

Items that are no longer in the latest response are marked as archived. They're hidden from the default view but preserved in the database. You can toggle archived items visible using the Filter menu in the toolbar.

Use this when:

• You want to focus on current items but keep a record of past ones
• You might need to reference old items occasionally
• You want the best of both worlds — a clean view with history available

# What Happens During a Sync

Here's what Weavestream does when it syncs an endpoint:

1. Makes the API request (handling pagination if configured)
2. Parses the response using your field mapping
3. Compares incoming items against existing ones using the ID field
4. New items are added to the database
5. Existing items are updated if their data has changed
6. Missing items are handled according to the retention mode (kept, deleted, or archived)
7. Unread counts in the sidebar are updated

# Tips

• Watch your API rate limits. If you have many endpoints on a 5-minute refresh, you might hit rate limits on some APIs. Consider using longer intervals or manual sync for less critical data.
• Use "Manual only" for large datasets. If an endpoint returns hundreds of items with pagination, automatic syncs can be resource-intensive. Sync manually when you actually need fresh data.
• Check the last sync time. If data seems stale, verify that automatic sync is running by checking the timestamp shown in the interface.

# Next Steps

• Configuring Endpoints — Set up endpoints and their parameters
• Item Actions — Manage items after they're synced