Docs
Powered by

# Adding Your First API Source

This guide walks you through connecting your first API to Weavestream. By the end, you'll have data flowing into the app and ready to browse.

# What You'll Need

Before you start, make sure you have:

  • The base URL for the API you want to connect (e.g., https://api.example.com)
  • Your authentication credentials (API key, token, username/password, etc.)
  • An idea of which endpoint you want to query (e.g., /v1/alerts or /api/tickets)

# Step 1: Add an API Source

A source represents a connection to a service. It holds your base URL and credentials, and you'll add one or more endpoints to it later.

  1. Click the + button at the bottom of the sidebar, then choose Add API Source. You can also use the menu bar or press Cmd+N.
  2. The Add Source wizard opens with three steps.

# Details

  • Name — Give your source a recognizable name (e.g., "GitHub," "NinjaOne," or "Stripe").
  • Base URL — Enter the root URL of the API. Endpoint paths will be appended to this. For example: https://api.github.com.

Tip: If you have an exported configuration file from another Weavestream installation, click Import from File to load it. Credentials are not included in exports for security, so you'll still need to enter those.

# Authentication

Choose the authentication method your API requires:

  • None — No authentication needed.
  • Bearer — Enter an access token. This is the most common method for modern APIs.
  • API Key — Enter an API key sent in the Authorization header.
  • Basic — Enter credentials in username:password format.
  • Query Param — For APIs that pass a token as a URL parameter (e.g., Plex's X-Plex-Token).
  • Credential Params — For APIs that send username and password as request body parameters.
  • Session — For APIs that require a login step to obtain a session token. You'll configure the login endpoint, credential fields, and how the token is extracted and injected.
  • OAuth 2.0 — For services that use OAuth. Choose between Authorization Code (opens a browser for login) or Client Credentials (machine-to-machine).

For a detailed breakdown of each authentication type, see Authentication Methods.

# Customize

  • Icon & Color — Pick an icon and color for your source. This helps you identify it quickly in the sidebar.
  • Refresh Interval — Choose how often Weavestream automatically syncs data: every 5 minutes, 15 minutes, 30 minutes, 1 hour, or manual only.

Click Add Source (or press Cmd+Return) to save.

# Step 2: Add an Endpoint

Now that you have a source, you need to add at least one endpoint to start pulling data.

  1. In the sidebar, hover over your new source and click the ... menu, then choose Add Endpoint. You can also press Cmd+Shift+N with the source selected.
  2. The Add Endpoint wizard opens.

# Endpoint Details

  • Endpoint Name — A descriptive name like "Open Alerts," "Recent Orders," or "All Repositories."
  • Method — Choose GET (for fetching data) or POST (for APIs that require a request body to query).
  • Path — The API path appended to your source's base URL (e.g., /v1/alerts). You'll see a preview of the full URL below.
  • Query Parameters — Add any key-value pairs your API needs (e.g., status=open or per_page=50).
  • Request Body — For POST requests, add parameters as key-value pairs. You can toggle between JSON and form-urlencoded encoding.

# Sample Data

Click Fetch Sample Data to make a test request. This does two things:

  • Confirms your connection and authentication are working
  • Discovers the available fields in the response, which you'll use in the next step

# Mapping

This is where you tell Weavestream how to read the API response:

  • ID Field (required) — The unique identifier for each item (e.g., id, uuid).
  • Date Field — The timestamp field (e.g., created_at, timestamp).
  • Status Field — A field to map to status badges (Critical, Warning, Info, OK). You can invert boolean values if needed.
  • Title Fields — One or more fields tried in order to display as the item title. Weavestream uses the first one that has a value.
  • Summary Fields — Same approach for the summary text shown below the title.
  • Array Path — If your items are nested inside the response (e.g., data.items or response.results), specify the path here.

As you configure mapping, a live preview on the right shows how your items will look.

For pagination, see Pagination.

Click Save Endpoint (or press Cmd+Return) to finish.

# Step 3: Sync Your Data

With your source and endpoint configured, it's time to pull in data:

  1. Click the Sync All button in the toolbar, or press Cmd+R.
  2. You'll see a progress indicator while Weavestream fetches your data.
  3. Once complete, your items appear in the item list.

That's it! You've connected your first API source. Select it in the sidebar to browse your items, or head to Navigating the Interface to learn your way around.

# Next Steps

© Copyright Spiffy Solutions Inc 2026. All rights reserved.