Getting started overview

Getting started with the Feedbin API involves a series of steps designed to ensure secure and authenticated access to your feed data. The process begins with creating an account, which is a prerequisite for using Feedbin's services, including its API. Once an account is established, you will obtain the necessary credentials—either your account username and password or a generated API token—for authentication. These credentials are then used to make your first programmatic request to the Feedbin API, verifying that your setup is correct and allowing you to begin integrating Feedbin's functionality into your applications.

The Feedbin API provides access to various functionalities, such as managing subscriptions, fetching feed content, and marking items as read or unread. It supports a RESTful architecture, utilizing standard HTTP methods (GET, POST, DELETE) for interactions and returning data primarily in JSON format. Understanding this foundational structure is crucial for effective API integration.

Below is a quick reference table summarizing the essential steps to get started with Feedbin's API:

Step What to Do Where
1. Create Account Sign up for a Feedbin account. A paid subscription is required for API access. Feedbin Pricing Page
2. Obtain Credentials Use your Feedbin username and password, or generate an API token. Feedbin Developers documentation
3. Make First Request Send an authenticated HTTP GET request to a basic endpoint, like fetching subscriptions. API client (e.g., cURL, Postman)
4. Explore Endpoints Review the API documentation for available endpoints and data models. Feedbin API reference

Create an account and get keys

To interact with the Feedbin API, you must first have an active Feedbin account. Feedbin operates on a subscription model, meaning a paid plan is required to access its features, including the API. You can review the available plans and sign up on the Feedbin pricing page. Once your account is created and active, you will have the necessary credentials for API authentication.

Authentication Methods

Feedbin's API primarily uses HTTP Basic authentication. This method involves sending your username and password (or an API token) with each request. HTTP Basic authentication transmits credentials in a base64-encoded string within the Authorization header of an HTTP request. While simple to implement, it is recommended to always use HTTPS to encrypt the communication channel and protect your credentials from interception, as described in the RFC 7617 HTTP Basic authentication scheme. All Feedbin API endpoints are served over HTTPS.

You have two options for providing credentials:

  1. Username and Password: You can use your Feedbin account username (typically your email address) and password directly for authentication.
  2. API Token: Feedbin also supports generating an API token, which can be used in place of your password. This method is often preferred for security reasons, as it allows you to revoke access without changing your primary account password. Details on how to generate an API token can be found in the Feedbin developers documentation.

For development and testing, using your username and password might be convenient. However, for production applications or when deploying code that accesses the API, using an API token is generally a more secure practice. API tokens function as a dedicated credential for programmatic access and can be managed independently of your main account login.

Your first request

After setting up your Feedbin account and understanding the authentication methods, you can make your first API request. This initial request serves to confirm that your authentication credentials are correct and that you can successfully communicate with the Feedbin API. A common starting point is to fetch a list of your subscriptions.

Using cURL

cURL is a command-line tool and library for transferring data with URLs, supporting various protocols, including HTTP. It's widely used for testing RESTful APIs directly from the terminal. To make your first request using cURL, replace YOUR_FEEDBIN_USERNAME and YOUR_FEEDBIN_PASSWORD_OR_TOKEN with your actual credentials.


curl -u "YOUR_FEEDBIN_USERNAME:YOUR_FEEDBIN_PASSWORD_OR_TOKEN" \
     "https://api.feedbin.com/v2/subscriptions.json"

Explanation:

  • curl: The command to invoke the cURL tool.
  • -u "YOUR_FEEDBIN_USERNAME:YOUR_FEEDBIN_PASSWORD_OR_TOKEN": This flag specifies the username and password (or API token) for HTTP Basic authentication. cURL will base64-encode these credentials and include them in the Authorization header.
  • "https://api.feedbin.com/v2/subscriptions.json": This is the Feedbin API endpoint for fetching user subscriptions. The .json extension indicates that the response format will be JSON.

Upon successful execution, this command will return a JSON array containing details of your current Feedbin subscriptions. Each object in the array will represent a single subscription, providing information such as the feed's title, URL, and subscription ID. An example successful response might look like this:


[
  {
    "id": 12345,
    "feed_id": 67890,
    "title": "Example Blog",
    "feed_url": "https://example.com/feed.xml",
    "site_url": "https://example.com/",
    "favicon_url": "https://example.com/favicon.ico",
    "folder_id": null,
    "created_at": "2023-01-01T12:00:00.000000Z",
    "public_id": "some-public-id"
  }
]

If you receive a 401 Unauthorized error, it indicates an issue with your authentication credentials. Double-check your username and password/token for accuracy.

Using a programming language (Python example)

For integration into an application, you'll typically use an HTTP client library in your preferred programming language. Here's an example using Python's requests library:


import requests

USERNAME = "YOUR_FEEDBIN_USERNAME"
PASSWORD_OR_TOKEN = "YOUR_FEEDBIN_PASSWORD_OR_TOKEN"
API_BASE_URL = "https://api.feedbin.com/v2"

def get_subscriptions():
    url = f"{API_BASE_URL}/subscriptions.json"
    try:
        response = requests.get(url, auth=(USERNAME, PASSWORD_OR_TOKEN))
        response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
        subscriptions = response.json()
        for sub in subscriptions:
            print(f"Subscription ID: {sub['id']}, Title: {sub['title']}")
    except requests.exceptions.HTTPError as err:
        print(f"HTTP error occurred: {err}")
    except requests.exceptions.ConnectionError as err:
        print(f"Connection error occurred: {err}")
    except requests.exceptions.Timeout as err:
        print(f"Timeout error occurred: {err}")
    except requests.exceptions.RequestException as err:
        print(f"An unexpected error occurred: {err}")

if __name__ == "__main__":
    get_subscriptions()

Explanation:

  • requests.get(): This function sends an HTTP GET request.
  • auth=(USERNAME, PASSWORD_OR_TOKEN): The requests library handles the base64 encoding for HTTP Basic authentication when a tuple of (username, password) is provided to the auth parameter.
  • response.raise_for_status(): This is a convenient method to automatically raise an HTTPError for bad responses (4xx or 5xx status codes).
  • Error Handling: The try-except block catches potential network and HTTP errors for more robust code.

Common next steps

Once you've successfully made your first API call to Feedbin, you can proceed to integrate more advanced functionalities into your application. The Feedbin API offers comprehensive capabilities for managing your RSS feeds and content. Here are some common next steps:

  1. Fetch Feed Contents: After retrieving subscription IDs, your next step might be to fetch the actual items (articles) from those feeds. The Feedbin API provides endpoints to retrieve entries for a specific feed or all unread entries across your subscriptions. This allows you to display content within your custom client or process it for other purposes. Consult the Feedbin API documentation for entries to understand the various filtering and pagination options.
  2. Manage Read States: A core feature of any RSS reader is the ability to mark items as read or unread. The Feedbin API allows you to programmatically update the read status of individual entries or batches of entries. This is essential for maintaining sync across devices and ensuring users don't see the same content repeatedly.
  3. Add/Remove Subscriptions: You can extend your application to manage user subscriptions directly through the API. This includes adding new feeds by URL, updating existing subscription details, or unsubscribing from feeds. This functionality is crucial for building a full-featured Feedbin client.
  4. Utilize Tags and Folders: Feedbin supports organizing feeds using tags and folders. The API provides endpoints to manage these organizational structures, allowing you to categorize subscriptions and entries programmatically. This can enhance the user experience by providing better content discoverability.
  5. Integrate with External Services: Feedbin can be integrated with other services, such as read-later apps (e.g., Instapaper, Pocket) or notification systems. The API enables you to build bridges between Feedbin and these external platforms, creating a more cohesive workflow. For example, you could set up a webhook to trigger an action in another service when a new item is added to a specific feed. General principles of webhook security should be considered when designing such integrations.
  6. Implement Pagination and Filtering: For applications dealing with a large number of feeds or entries, understanding and implementing pagination and filtering parameters is vital. The Feedbin API uses standard pagination techniques to limit the number of results returned per request and offers various filters to narrow down content based on criteria like read status, feed ID, or date.
  7. Error Handling and Rate Limits: As you build out your integration, implement robust error handling for various API responses (e.g., 4xx client errors, 5xx server errors). Also, be aware of any API rate limits to prevent your application from being temporarily blocked due to excessive requests. While Feedbin's specific rate limits are documented, general best practices for API consumption should always be followed.

Troubleshooting the first call

Encountering issues during your first API call is a common part of the development process. Here are some troubleshooting tips for common problems when interacting with the Feedbin API:

401 Unauthorized

This is the most frequent error for initial API calls and indicates an authentication failure.

  • Incorrect Credentials: Double-check your Feedbin username (which is typically your email address) and password or API token. Ensure there are no typos, extra spaces, or case sensitivity issues.
  • No Active Subscription: The Feedbin API requires an active, paid subscription. If your subscription has lapsed or you are on a trial that doesn't include API access, you will receive a 401 error. Verify your account status on the Feedbin website.
  • Incorrect HTTP Basic Header: Ensure your HTTP client is correctly formatting the Authorization: Basic <base64_encoded_credentials> header. Tools like cURL and libraries like Python's requests handle this automatically when using the -u flag or auth parameter, but if you're manually constructing headers, ensure the base64 encoding is correct. The format should be username:password_or_token encoded.
  • Using `https` vs. `http`: The Feedbin API requires HTTPS. Using plain HTTP will result in connection errors or unauthorized responses because credentials are not securely transmitted.

404 Not Found

This error indicates that the API endpoint you are trying to access does not exist or is incorrect.

  • Incorrect Endpoint URL: Verify the exact URL path against the Feedbin API documentation. Pay close attention to version numbers (e.g., /v2/), resource names (e.g., /subscriptions.json), and file extensions (.json).
  • HTTP Method Mismatch: Ensure you are using the correct HTTP method (GET, POST, DELETE) for the specific endpoint. For example, trying to POST to a GET-only endpoint might result in a 404.

Network or Connection Errors

These errors often manifest as timeouts or connection refused messages.

  • Internet Connectivity: Ensure your machine has a stable internet connection.
  • Firewall/Proxy Issues: Corporate firewalls or local security software might be blocking outgoing connections to api.feedbin.com. Check your network configuration or consult your IT administrator.
  • DNS Resolution Problems: Ensure that api.feedbin.com resolves correctly to an IP address. You can test this using tools like ping or nslookup.
  • API Downtime: Although rare, the Feedbin API might experience temporary downtime. Check Feedbin's official status page or social media channels for any announcements.

Empty or Unexpected Response

Sometimes the request succeeds, but the response is not what you expect.

  • No Subscriptions: If you are fetching subscriptions and receive an empty JSON array ([]), it might simply mean your Feedbin account currently has no active subscriptions. Try adding a feed via the Feedbin web interface and then re-running your API call.
  • Filtering Parameters: If you're fetching entries and get fewer results than expected, check if you're applying any filters (e.g., read=true, since=some_date) that are narrowing down the results. Review the Feedbin API documentation for available parameters.

When troubleshooting, always examine the full HTTP response, including status codes, headers, and the response body. This information is critical for diagnosing the exact nature of the problem.