> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/start-here/ai-agents/content-analytics-and-distribution/manage-private-feeds-and-listeners.md).

# Manage private feeds and listeners

Make a show private, then add, pause, remove, or reset its listeners with your assistant, safely.

A private feed lets only invited listeners subscribe to a show. Your assistant can make a show private or public, list its listeners, add a listener, change the status of a listener, and send a password reset.

* **Listeners are not team members.** A listener can only hear a private show. To invite a person who works on a show or the account, the assistant calls `find_in_podigee` for the right page.
* **Comments are not read here.** Listener comments on episodes are something else. No tool reads or approves them. The assistant calls `find_in_podigee` for the Comments page, or see [Moderate comments](https://docs.podigee.com/documentation/create-and-publish/publishing-and-distribution/moderate-comments.md).

Each tool, with its parameters and errors, is on [Private feed tools](https://docs.podigee.com/documentation/start-here/ai-agents/mcp-tools/private-feeds.md). For the steps in the Podigee app, see [Restrict a podcast to invited listeners](https://docs.podigee.com/documentation/create-and-publish/publishing-and-distribution/restrict-a-podcast-to-invited-listeners.md).

## How private feeds work

* Your plan must include private feeds. Some plans also limit the number of listeners across all shows of the owner.
* A listener belongs to one show and has an email address or a username.
* A listener has one of these statuses: `pending`, `active`, `inactive`, or `resent`.
* An optional expiry time (`expires_at`) ends the access of a listener on its own.
* Deactivation stops the access of one listener and keeps the record. You can activate it again.
* Deletion removes the listener record permanently.
* The public feed URL (web address) identifies the show. The private feed URL of a listener contains an access credential. Treat it like a password.
* The tools return only the public feed URL. They never return a private feed URL or an access token.
* A show with a private feed cannot be submitted to directories. See [Distribute a podcast](https://docs.podigee.com/documentation/start-here/ai-agents/content-analytics-and-distribution/distribute-a-podcast.md).

## What you need

* The ID (identifier) of the show. The assistant finds it with `list_podcasts`.
* Permission to edit the information of the show.
* The right scopes for the connected assistant:
  * `list_listeners` needs `mcp:listeners:read`.
  * `create_listener`, `update_listener_status`, and `send_listener_password_reset` need `mcp:listeners:write`.
  * `manage_feed_access` needs `mcp:listeners:read`, `mcp:listeners:write`, and `mcp:podcasts:write` for every call, also a call that only reads. With a read-only connection, the assistant uses `list_listeners` instead.

The [scope table](https://docs.podigee.com/documentation/start-here/ai-agents/mcp-reference/authorization-and-scopes.md) shows all scopes. A connection without a write scope still sees the write tools. A call then fails with `insufficient_scope`. Write tools disappear only when writes are off for the account or the server.

## Make a show private or public

Use `manage_feed_access`. Make the show private before you add the first listener.

1. Ask your assistant, for example: "Is Second Cup Stories private? Who can listen?"
2. The assistant calls `manage_feed_access` with `podcast_id` alone. It reads `feed_info` (`public_feed_url`, `protected`) and the first 25 listeners.
3. Ask for the change, for example: "Make Second Cup Stories private."
4. The assistant previews the change with `feed_protection` and `dry_run: true`. Use `enable` (or `on`) to make the show private, and `disable` (or `off`) to make it public again.
5. Review `proposed_protected` and the effect on your listeners. Say yes in a later message.
6. The assistant sends the same change with the `confirm` value from the preview.
7. The assistant calls `manage_feed_access` with `podcast_id` alone again and checks `feed_info.protected`.

One confirmed call makes one change. Send a protection change and a listener change in separate calls. Podigee refuses a confirmed call that combines them. The general preview and confirm rule is on [Preview and confirm changes](https://docs.podigee.com/documentation/start-here/ai-agents/work-safely/preview-and-confirm-changes.md).

**Expected result:** `feed_info.protected` shows the state that you approved. The listener records stay as they were.

**If it fails:**

* `plan_limit_reached` with the entitlement `protected_podcasts`: the plan does not include private feeds. A plan upgrade enables them.
* A permission error: the connected user cannot edit this show.
* Before you make a show public, know that everybody can then subscribe without a credential. To stop the access of one listener, deactivate that listener instead.

**Next step:** [Add a listener](#add-a-listener).

## List listeners

1. Ask your assistant, for example: "List the listeners of Second Cup Stories."
2. The assistant calls `list_listeners` with `podcast_id`. Without `podcast_id`, the list holds the listeners of all shows that you can edit.
3. Review the listener ID, the email address or username, the status, and the expiry time.
4. When two listeners look alike, match the person by more than one detail.
5. If `pagination.next_offset` is present, the assistant asks for the next page.
6. Keep the exact listener ID for any change.

A page holds 25 listeners by default and 100 at most.

**Expected result:** you have the exact listener record and its access status.

**If it fails:** an empty list can mean that the show has no listener yet, or that the show ID or your permission is wrong. Check both. Do not guess a private URL or a credential.

**Next step:** [Change the status of a listener](#activate-deactivate-or-delete-a-listener).

## Add a listener

**What you need:**

* The feed of the show is private.
* The plan includes private feeds, and the listener limit is not reached.
* The email address or the username of the listener, and an optional expiry time.

**Steps:**

1. Ask your assistant, for example: "Invite <riley.park@example.com> to Second Cup Stories until the end of the year."
2. The assistant previews `create_listener` with `attributes` (`podcast_id`, `email` or `username`, optional `password`, optional `expires_at`) and `dry_run: true`.
3. Review the show, the email address or username, the expiry time, and `password_supplied`.
4. Say yes in a later message.
5. The assistant sends the same request with the `confirm` value and an `idempotency_key`.
6. Keep the new listener ID and check its status.
7. The assistant lists the listeners of the show and finds the new record.

An email address without a password gives a `pending` listener, who gets an invitation. A password gives an `active` listener. Send a password to the listener only through a secure channel that you approved.

`manage_feed_access` can also add a listener with `listener_attributes`. The rules are the same.

**Expected result:** Podigee creates one listener in the show, with the status `pending` or `active`.

**If it fails:**

* The feed of the show is not private: a listener would give no access. Make the show private first, then add the listener.
* `plan_limit_reached` with the entitlement `protected_podcasts`: the plan of the show does not include private feeds.
* `plan_limit_reached` with the entitlement `private_feed_listeners`: the listener limit of the plan is reached. The error gives `limit` and `used`. A plan upgrade raises the limit.
* "Listener email is already in use.": the show already has a listener with this email address.
* An invalid expiry time: correct it and preview again.

**Next step:** [Give a listener access](#give-a-listener-access-to-the-private-feed).

## Activate, deactivate, or delete a listener

Choose the action that removes the least.

| Action       | Result                                              | Confirm                                 |
| ------------ | --------------------------------------------------- | --------------------------------------- |
| `activate`   | Sets the status to `active`.                        | Not needed. The change applies at once. |
| `deactivate` | Sets the status to `inactive` and keeps the record. | Not needed. The change applies at once. |
| `delete`     | Removes the listener record permanently.            | Needed, after a preview.                |

1. The assistant lists the listeners and finds the exact listener ID.
2. For `activate` or `deactivate`: the assistant shows you the listener and the action first. Then it calls `update_listener_status` with `listener_id` and `action`. Without `dry_run: true`, the change applies at once. To see a preview first, ask for `dry_run: true`.
3. For `delete`: the assistant previews with `dry_run: true`. Review the listener. Say yes in a later message. The assistant sends the `confirm` value from the preview.
4. The assistant lists the listeners again and checks the result.

Podigee refuses a delete confirm that arrives less than 15 seconds after its preview, with `confirmation_too_early`. The confirm value stays valid for 15 minutes. Details are on [Preview and confirm changes](https://docs.podigee.com/documentation/start-here/ai-agents/work-safely/preview-and-confirm-changes.md). This tool takes no `idempotency_key`.

**Expected result:** `activate` and `deactivate` return the changed record. `delete` returns the removed record with `deleted: true`.

**If it fails:** if the preview shows the wrong listener, stop. Go back to the list of the show and select the correct listener ID.

**Next step:** [Protect listener data](#protect-listener-data-and-private-urls).

## Send a password reset

1. The assistant lists the listeners and finds the exact listener ID.
2. Check the email address, the show, and the status of the listener.
3. The assistant previews `send_listener_password_reset` with `listener_id` and `dry_run: true`.
4. Review the preview. Say yes in a later message.
5. The assistant sends `dry_run: false`, the `confirm` value, and an `idempotency_key`. Both are required to send.
6. Keep the returned `operation_id`. Check that the answer has `reset_email_sent: true` for the correct listener ID.

Podigee records the delivery before it gives the email to the mail service. A retry with the same `idempotency_key` does not send a second email.

**Expected result:** Podigee sends one reset email to the listener.

**If it fails:**

* `confirmation_required`: the `confirm` value is missing. Preview again.
* `delivery_outcome_unknown`: Podigee does not know if the email went out. Do not send another reset at once. Ask the listener to check the mailbox. Send a new reset with a new `idempotency_key` only when you decide to.

**Next step:** [Give a listener access](#give-a-listener-access-to-the-private-feed).

## Give a listener access to the private feed

The tools do not return the private feed URL or its token. Never build a private URL by adding a guessed value to the public feed.

1. The assistant lists the listeners of the show and finds the exact listener ID.
2. Check the status and the expiry time of the listener.
3. If the listener is `pending`, the listener completes the Podigee invitation.
4. If the listener lost the password, send a password reset to the registered email address.
5. The listener gets the private feed from the Podigee listener page.

**Expected result:** the listener gets or restores access. The credential does not appear in a chat, a log, or a support message.

**If it fails:** if the listener gets no email, check the stored email address and the status. Do not share the details widely. Give a username and password only through a secure channel that you approved.

**Next step:** [Protect listener data](#protect-listener-data-and-private-urls).

## Protect listener data and private URLs

Email addresses, usernames, private feed URLs, passwords, and access tokens are personal or secret data.

* Give the listener scopes only to an assistant that manages private feeds.
* Filter listener lists by show.
* Treat a complete private feed URL like a password. Do not paste it into a chat, a log, a ticket, a screenshot, or a document.
* Do not ask an assistant to repeat or change an access token.
* Use invitations and password resets. Do not send credentials by hand.
* Never put a password in a preview note or a support message.
* For Podigee Support, give the show ID, the listener ID, the status, the expiry time, the operation ID, and the error code. Hide personal data that Support does not need.
* Deactivate a listener to stop access and keep the record.
* Remove an assistant that must not manage listener data any more. See [Manage connected assistants](https://docs.podigee.com/documentation/start-here/ai-agents/connect-and-authorize/manage-connected-assistants.md).

**Next step:** [Private feed tools](https://docs.podigee.com/documentation/start-here/ai-agents/mcp-tools/private-feeds.md) has the full contract of each tool.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.podigee.com/documentation/start-here/ai-agents/content-analytics-and-distribution/manage-private-feeds-and-listeners.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
