# Configuring Endpoints

Endpoints define the specific API queries Weavestream makes within a source. Each endpoint has its own path, method, parameters, and field mapping. This guide covers the endpoint configuration options in detail.

To add an endpoint to a source:

1. Hover over the source in the sidebar and click the ... menu
2. Choose Add Endpoint, or press Cmd+Shift+N
3. The Add Endpoint wizard opens with three steps: Details, Sample Data, and Mapping

Give your endpoint a descriptive name that tells you what data it fetches. Good examples:

• "Open Alerts"
• "Recent Transactions"
• "All Repositories"
• "Failed Payments"

Choose the method your API expects:

• GET — The standard method for fetching data. Query parameters are appended to the URL.
• POST — Used by some APIs that require a request body to define what data you want. For example, search endpoints or GraphQL APIs.

The path is appended to your source's base URL. For example, if your source URL is https://api.github.com and your path is /repos/myorg/myrepo/issues, the full URL will be https://api.github.com/repos/myorg/myrepo/issues.

A preview of the full URL appears below the path field so you can verify it looks correct.

Add key-value pairs that are appended to the URL as query string parameters. For example:

This would produce: ?state=open&per_page=50&sort=created

Click Add Query Parameter to add more. Authentication parameters (like API keys configured at the source level) are added automatically — you don't need to include them here.

When using the POST method, you can add parameters to the request body:

• Each parameter has a Key, a Type (String or Boolean), and a Value
• Click Add Body Parameter to add more
• Toggle Use Form-URLEncoded Body to switch between JSON and form-encoded formats

Use JSON (the default) for most modern APIs. Use form-urlencoded for older APIs or those that specifically require it.

Before configuring field mapping, it helps to fetch sample data from the API. This step lets you:

1. Verify your connection — Confirms that the URL, authentication, and parameters are all working
2. Discover available fields — Weavestream analyzes the response and lists all the fields it finds

Click Fetch Sample Data to make a test request. If successful, you'll see a green checkmark and the raw JSON response below. The response is truncated for display, but all fields are discovered.

If the fetch fails, check your source's base URL, authentication credentials, and the endpoint path. The error message will usually point you in the right direction.

Field mapping tells Weavestream how to interpret each item in the API response. This is what turns raw JSON into the structured items you see in the app.

Every item needs a unique identifier. Select the field that uniquely identifies each record. Common examples: id, _id, uuid, ID.

The timestamp for each item. This is used for sorting by date and displaying when items were created or updated. Common examples: created_at, createdAt, timestamp, date, updated_at.

Map a field to display as a status badge on each item. Status badges appear as colored indicators:

• Critical — Red
• Warning — Orange
• Info — Blue
• OK — Green

If the field contains boolean values, you can toggle Invert boolean value to flip the meaning (e.g., true becomes Critical instead of OK).

Titles are what you see in the item list. You can specify multiple fields as a fallback chain — Weavestream tries each one in order and uses the first that has a value. This is useful when different items might store their title in different fields.

For example, you might set:

1. title
2. name
3. subject

Click Add Title Field to add more fallback options.

Summary text appears below the title in the item list (up to two lines). Like titles, you can specify multiple fields as a fallback chain. Click Add Summary Field to add more.

If the items in your API response are nested inside a wrapper object, specify the path to the array. For example, if your response looks like:

{
  "status": "ok",
  "data": {
    "items": [
      { "id": 1, "title": "First item" },
      { "id": 2, "title": "Second item" }
    ]
  }
}

You would set the Array Path to data.items.

Leave this blank if the response is already an array at the top level.

As you configure mapping, the right side of the window shows a live preview of how your items will look. This updates in real time as you change fields, so you can experiment until everything looks right.

To edit an existing endpoint:

1. Right-click the endpoint in the sidebar
2. Choose Edit Endpoint
3. Make your changes and save

You can disable an endpoint without deleting it. Disabled endpoints are skipped during syncs but keep their configuration and data.

• Right-click the endpoint in the sidebar and choose Enable or Disable

• Field Mapping — More details on field discovery and JSONPath
• Pagination — Handle APIs that return data across multiple pages
• Syncing & Refresh — Control when and how data is updated