PostRSS REST API v1: Creating Targets and Reading Reports From Code

The PostRSS REST API v1 lets developers do from their own code what customers normally do in the web app: sign in, list connected accounts, create and update targets, upload a CSV source, read posting reports and check plan usage. The PostRSS integrations page describes it simply: everything the plugins do is available through the REST API, so you can build your own integration for a platform that has no official plugin.

This guide explains how the API is organised, how authentication works, how a target is described, what the reports return and which practices keep an integration safe and polite. It is based on the public API documentation and the live PostRSS pages. Always check the interactive documentation for the exact fields of the current version, because details can be extended over time, and never test with credentials or accounts you cannot afford to expose.

What the API Is For

PostRSS is an RSS auto-posting service: it checks an RSS or Atom feed, or a CSV file, and publishes new items to social networks, messengers, team chats and blogs. The web app is the usual way to set that up. The API is for cases where a person clicking through forms is not practical.

• Agencies and platforms that create many targets for client sites and want consistent settings.
• Custom CMS or shop software that has no official plugin and should create the feed and the target itself.
• Internal dashboards that show posting reports and statistics next to other business data.
• Mobile or partner apps that need account sign-in, target management and reports. The documentation calls it a mobile and partner API.
• Automation scripts that check the plan, upload a CSV and read the result.

If you only need to send each new feed item to another system, a webhook may be simpler than the API; our guide to PostRSS webhooks, Zapier and n8n covers that route. The API is for managing PostRSS itself, while webhooks are for receiving its output.

How the API Is Organised

All requests and responses use JSON in UTF-8, and times are given in ISO 8601 format with an offset. The interactive documentation, built on the OpenAPI format, lists every endpoint and lets you try requests. The table groups the main areas as the documentation describes them.

The documentation is available at app.postrss.com/api/v1/docs, and the machine-readable description follows the OpenAPI specification, so you can generate a client library in most languages.

Signing In and Keeping the Token Safe

Requests are authenticated with a bearer token in the Authorization header. You obtain it by signing in through the login endpoint with an email and password, or through the social sign-in endpoint for Google, Facebook or Apple. The response contains the token, its type and its expiry time, and the documentation notes that the token is shown once, so store it securely straight away.

1. Sign in from the server side of your integration, never from a public web page that would expose credentials.
2. Store the token in a secrets store or protected configuration, not in source code or logs.
3. Send it as a bearer token on each request, as described in the bearer token standard.
4. Watch the expiry and sign in again when needed.
5. Revoke what you no longer use. The integrations page explains that tokens appear under Devices in the user’s account and can be revoked at any time, and the API has endpoints to list and revoke them as well.

Treat the token like a password: whoever holds it can act as the user. Use a separate account or a limited team member for an integration where you can, and rotate tokens when staff change. Team members get the owner’s data with the same restrictions as on the website, and actions reserved for the owner, such as disconnecting an account, stay reserved.

From Accounts to a Working Target

A target is a destination, such as a Facebook Page, a Telegram channel or a Bluesky account, together with one or more sources that feed it. Creating one through the API follows the same logic as the web app.

1. Connect the account. Social accounts must be connected before they can be used. For networks that need an authorisation flow, the API starts it and the owner approves it in a browser. For others, such as a Telegram channel, a Discord webhook, Bluesky, Matrix or a generic webhook, there are connection endpoints that take the required details.
2. List what is available. Target option endpoints return the pages, channels, boards or rooms you can post to, with the identifiers you need.
3. Describe the target. Send a name, the target reference for the chosen network and the list of sources.
4. Define each source. A source is either an RSS URL or a CSV file, with its own settings.
5. Read the result. The response returns the created target, including identifiers for later updates.

Per-source settings mirror the options in the web app: the message format, which can be built from the item title, the description, the page title or static text; additional query parameters, for tracking such as UTM values; how often to check; the publishing order, such as newer first or older first; the maximum number of posts per update; the date and hours to post from and to; whether to catch up older items; keyword filters to include or exclude; and hashtag options. The documentation notes that the check frequency must respect the minimum for your plan, and that exact posting times are for paid plans.

Updating Without Surprises

The documentation for updates gives a clear rule: send the full object. To change a target, fetch it with a GET request, modify the fields you want and send the whole thing back with a PUT. This avoids accidental loss of settings that you did not mention. Build your integration around that pattern: read, change locally, write back.

Handle errors carefully. Errors use a simple message with an HTTP error status, and a plan restriction is reported with a specific error code so your code can tell the difference between a bad request and a limit of the plan. Do not retry blindly: a failed creation may mean a missing account, and repeating the same call will not help. If you receive a status that signals too many requests, wait before trying again; the MDN page on the 429 status explains the usual pattern of backing off.

Reading Reports and Statistics

Reports are where the API pays off for monitoring. For each target, the report endpoint returns the processing history: each row shows the source, the date, whether the run succeeded, a failure reason if it did not, the number of items found and the number posted. A second endpoint lists the items seen in one run, with the title, link, message, image link, date and a status, such as processed, skipped, failed, already posted, blocked by the posts-per-update limit or filtered out by a keyword filter. A statistics endpoint gives posting totals.

With these you can build a small dashboard that answers the questions customers ask: did the post go out, and if not, why? Alert on failed runs, show items that were filtered, and compare found and posted counts to spot a source that suddenly stops producing items. Our article on auditing the posting history describes the same questions from the web app’s side.

CSV Sources and Plan Checks

If your system holds content in a spreadsheet or database, you can generate a CSV file and upload it through the CSV endpoint; each row becomes one post. CSV sources require the Professional plan or above, according to the features page, so check the plan first. The subscription endpoint returns your current plan, limits and usage in read-only form, which lets your integration warn a user before they hit a limit, and the plans endpoint lists the public plans. Our guide to CSV sources explains how to design the file.

A Small First Project

A good first project is a read-only status page. Sign in with a test account, list the targets, fetch the report for each one and show the latest run with its result and the number of items posted. It touches authentication, listing and reporting without changing anything, so mistakes are harmless. Once that works, add a second step that creates a target for a test channel from a feed address, and then a third that updates one setting using the read-modify-write pattern. Keep a short document of the calls you use, the fields you rely on and the error handling you chose, so that the next developer can maintain the integration without guessing.

Good Practice for Integrations

• Be idempotent. Before creating a target, list existing ones so that a repeated job does not create duplicates.
• Log requests and responses, without tokens or personal data, so problems can be traced.
• Respect limits. Keep request rates modest and back off on errors.
• Test in a separate account with a free plan and a test channel before touching customer targets.
• Do not automate what the platforms forbid. PostRSS posts to Facebook Pages only, since Meta closed the Groups publishing API in April 2024, so design your product around Pages.
• Tell users what you do. If your tool creates targets on their behalf, explain it plainly and show them how to review or remove them in PostRSS.

If you are deciding whether to write custom code at all, read build versus buy automation. For an overview of the product, see our PostRSS page.

Frequently Asked Questions

Where is the API documentation?

The interactive documentation is at app.postrss.com/api/v1/docs, and the machine-readable OpenAPI description is published alongside it.

Is the API free to use?

The integrations page says integrations do not cost extra and that you pay only for your PostRSS plan. Plan limits still apply to what you can create.

How do I authenticate?

Sign in through the login endpoint and use the returned bearer token in the Authorization header. The token is shown once, so store it securely.

Can I update only one field of a target?

The documentation says to fetch the target, change what you need and send the full object back with PUT.

Can I read why a post did not go out?

Yes. The report for a target shows each run with a failure reason, and the item list shows a status for each item, such as filtered, skipped or failed.

Can the API post to Facebook Groups?

No. PostRSS posts to Facebook Pages only, because Meta closed the Groups publishing API in April 2024.

The Bottom Line

The PostRSS REST API v1 gives developers the same control as the web app: sign in with a bearer token, connect accounts, create and update targets with their sources, upload CSV files, read reports and statistics, and check plan usage. Keep tokens secret, follow the read-modify-write rule for updates, handle errors and limits calmly, and test in a separate account. Used this way, it lets your own system run PostRSS without manual steps.