canonical: https://jentic.com/apis/castos.com/castos # Castos API Jentic publishes the only available OpenAPI specification for Castos API, keeping it validated and agent-ready. Castos is a podcast hosting platform for creators and the v2 API exposes podcast and episode management together with private subscriber controls used by paid and members-only feeds. The API supports listing, creating, updating, and deleting podcasts and episodes, plus full lifecycle management of private subscribers including bulk create, update, revoke, and reactivate operations. It also returns the supported podcast category taxonomy used when classifying a show. ## For AI agents Manage podcasts, episodes, and private subscribers on Castos, including bulk operations for invite-only feeds and reactivation of revoked subscribers. ## Scope Does not handle audio recording, transcription, or listener analytics - use for managing Castos podcasts, episodes, and private subscribers only. ## Capabilities - Create, update, and delete podcasts hosted on a Castos account - Publish, edit, and remove individual episodes within a podcast - Add private subscribers to a podcast for paid or members-only feeds - Bulk create, update, and revoke private subscribers in a single API call - Look up a private subscriber by email or by subscriber id - Reactivate a revoked Castos private subscriber - Retrieve the Castos podcast category taxonomy for tagging shows ## Use cases ### Membership-driven podcast access Membership platforms can sync their paid subscribers into a Castos private feed using POST /private-subscribers and POST /create-private-subscribers for bulk imports. When a member cancels, POST /revoke-private-subscribers cuts feed access; reactivation endpoints restore it without re-collecting their email. Example prompt: POST /create-private-subscribers with a list of 50 customer email addresses against podcast_id=42 to grant feed access in one batch. ### Programmatic episode publishing Production teams can post finished episodes to Castos using POST /podcasts/{podcast_id}/episodes with the audio URL, title, and show notes, then update metadata later via the corresponding update endpoint. This removes the manual step of uploading episodes via the Castos web UI for every release. Example prompt: POST /podcasts/{podcast_id}/episodes with title, audio_url, and publish_at set to next Tuesday at 06:00 UTC. ### Subscriber lifecycle management Customer success workflows can keep Castos in sync with the source of truth by looking up a subscriber via GET /private-subscribers/email/{email_address}, then revoking, reactivating, or deleting based on billing status. Bulk endpoints make this efficient when running monthly reconciliation. Example prompt: GET /private-subscribers/email/jane@example.com, then POST /private-subscribers/reactivate/email/jane@example.com if she has paid the outstanding invoice. ### AI agent podcast operations via Jentic An AI ops agent can take a list of new paid customers from a billing system and add them all to the right Castos private feed in one Jentic-driven call, with credentials kept inside your Jentic One instance. The same agent can later trigger episode publication when a finished audio asset arrives. Example prompt: Search Jentic for 'bulk create Castos private subscribers', load POST /create-private-subscribers, and execute it with the customer email batch. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /podcasts | List podcasts on the account | | POST | /podcasts/{podcast_id}/episodes | Create a new episode | | POST | /private-subscribers | Add a private subscriber to a podcast | | POST | /create-private-subscribers | Bulk add private subscribers | | POST | /revoke-private-subscribers | Bulk revoke private subscribers | | POST | /private-subscribers/reactivate/email/{email_address} | Reactivate a subscription by email | | GET | /get-categories | List supported podcast categories | ## Key resources - **Podcasts** — CRUD operations on podcast shows hosted in a Castos account. - **Episodes** — Create, list, update, and delete episodes within each podcast. - **Private Subscribers** — Manage individual and bulk private subscriber records, including revoke and reactivate. - **Categories** — Read the supported podcast category taxonomy. ## Why Jentic - **Setup:** Wiring the Castos API by hand means sending your API token as a bearer credential on every call and working across the podcast, episode, and subscriber routes on the app.castos.com host yourself. Through Jentic you install once, import the Castos API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Castos puts the podcast id in the URL path (/podcasts/{podcast_id}/episodes), so a rule can pin your agent to one podcast for publishing episodes. You choose the operations it may call, so private subscriber creation, revocation, and reactivation are not included unless you add them. - **Credential handling:** Your Castos API token is stored once, encrypted, by your own Jentic One instance and injected as the bearer token at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'add a Castos private subscriber' or 'publish a podcast episode', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Spotify Web API** — Spotify is the listener-side platform that consumes podcast feeds Castos publishes. - **Castmagic API** — Castmagic produces transcripts and show notes that you publish back into Castos episodes. - **SquadCast API** — SquadCast handles remote podcast recording sessions whose output you upload to Castos. ## FAQ ### Why is there no official OpenAPI spec for Castos API? Castos publishes browsable docs but no machine-readable OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Castos API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Castos API use? The Castos API uses HTTP bearer token authentication. You generate the API token from the Castos dashboard and include it as Authorization: Bearer in every request. Through Jentic the token is stored in your Jentic One instance and injected at execution time, so it never appears in agent prompts. ### Can I bulk add private subscribers to a Castos podcast? Yes. POST /create-private-subscribers accepts a list of subscribers in a single request, and matching bulk endpoints exist for update (/update-private-subscribers) and revoke (/revoke-private-subscribers). Use these instead of looping over the per-subscriber endpoint when syncing membership lists. ### What are the rate limits for the Castos API? Castos does not document explicit numeric rate limits in this OpenAPI spec. Prefer the bulk private-subscriber endpoints over per-record loops, and avoid tight polling on /podcasts and /podcasts/{podcast_id}/episodes - use scheduled syncs instead. ### How do I reactivate a cancelled Castos subscriber? Call POST /private-subscribers/reactivate/{subscriber_id} if you know the subscriber id, or POST /private-subscribers/reactivate/email/{email_address} to reactivate by email. This restores feed access without requiring the subscriber to re-enter their email. ### How do I publish a Castos episode through Jentic? Run pip install jentic, search Jentic with the query 'publish a podcast episode to Castos', load the POST /podcasts/{podcast_id}/episodes schema, and execute it with title, audio_url, and an optional publish_at timestamp. Jentic handles the bearer token automatically. ### Can I limit what my agent is allowed to do with the Castos API? Yes. Because you run Jentic One yourself, your own rules decide which Castos operations and credentials the agent can use. Since the podcast id sits in the URL path, such as POST /podcasts/{podcast_id}/episodes, you can pin the agent to a single podcast for publishing episodes. You also choose the operations it may call, so private subscriber creation, revocation, and reactivation stay off limits unless you add them.