# Understanding API Sources & Endpoints

Weavestream organizes your API connections using two levels: Sources and Endpoints. Understanding how they relate will help you set things up efficiently.

# Sources

A source represents a single API service — for example, GitHub, Stripe, or NinjaOne. Each source holds:

• A base URL (e.g., https://api.github.com)
• Authentication credentials (stored securely in your Mac's Keychain)
• Custom headers that are sent with every request
• A refresh interval for automatic syncing
• An icon and color for quick identification in the sidebar

Think of a source as your connection to a service. It handles the "how do I talk to this API?" part.

# Endpoints

An endpoint is a specific query within a source. One source can have many endpoints. For example, a GitHub source might have:

• An "Open Issues" endpoint querying /repos/myorg/myrepo/issues?state=open
• A "Pull Requests" endpoint querying /repos/myorg/myrepo/pulls
• A "Notifications" endpoint querying /notifications

Each endpoint has its own:

• Path appended to the source's base URL
• HTTP method (GET or POST)
• Query parameters and request body
• Field mapping that tells Weavestream how to read the response
• Pagination settings for APIs that return data across multiple pages
• Retention mode controlling what happens to old items

# How Data Flows

Here's what happens when Weavestream syncs:

1. Weavestream takes the source's base URL and appends the endpoint's path
2. It adds the source's authentication and headers, plus any endpoint-specific query parameters
3. It makes the API request (handling pagination if configured)
4. The response is parsed using the endpoint's field mapping — extracting the title, summary, date, status, and ID from each item
5. Items are saved locally in Weavestream's database
6. The items appear in the sidebar under their endpoint

# Managing Sources

You can manage your sources from the sidebar:

• Hover over a source and click the ... menu to access options
• Sync Now — Immediately refresh all endpoints in this source
• Add Endpoint — Add a new query to this source
• New Filter — Create a Smart Filter scoped to this source's data
• Edit Source — Change the name, URL, auth, headers, or refresh interval
• Export Configuration — Save the source config to a file (credentials are excluded for security)
• Re-authenticate — Re-run the OAuth flow (only shown for OAuth Authorization Code sources)
• Delete Source — Remove the source and all its endpoints and data

# One Source, Many Endpoints

A common pattern is to create one source per service, then add multiple endpoints for different views of that service's data. For example:

Source: "Stripe" (https://api.stripe.com/v1)

• Endpoint: "Recent Charges" → /charges?limit=50
• Endpoint: "Disputes" → /disputes
• Endpoint: "Failed Payments" → /charges?status=failed

This keeps your authentication in one place and lets you organize queries logically.

# Next Steps

• Authentication Methods — Configure credentials for your source
• Configuring Endpoints — Set up endpoint paths, parameters, and bodies
• Field Mapping — Tell Weavestream how to read API responses