For testing below, you will need to use your Network ID as a parameter for requests. Please contact help@supportingcast.fm if you are unsure about what your Network ID is.", "summary": "API to manage your Supporting Cast account and products" }, "servers": [ { "url": "https://api.supportingcast.fm/v2/{network_id}", "variables": { "network_id": { "description": "Unique identifier for the network being managed", "default": "{Your Network ID}" } } } ], "tags": [ { "name": "Administrators", "description": "Administrators of the network" }, { "name": "API Tokens", "description": "API tokens used to authenticate requests to the API" }, { "name": "Downloads" }, { "name": "Episodes", "description": "Episodes within feeds" }, { "name": "Feeds", "description": "RSS feeds" }, { "name": "Posts", "description": "Posts (written content) published within a network" }, { "name": "Purchases", "description": "User one-time purchases" }, { "name": "Security Events", "description": "Security-relevant activity within the network, for ingestion into a SIEM" }, { "name": "Subscriptions", "description": "User subscriptions" }, { "name": "Subscription Plans", "description": "Subscription plans / audiences representing tiers or groupings of access." }, { "name": "Subscription Prices", "description": "Pricing options for the subscription plans." }, { "name": "Users", "description": "Audience users, a.k.a. listeners or members" } ], "paths": { "/api_tokens": { "get": { "summary": "List API Tokens", "description": "Lists all active (non-revoked) API tokens for the network.", "operationId": "list-api-tokens", "tags": [ "API Tokens" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiToken" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/api_tokens" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create API Token", "description": "Creates a new API token. The plaintext token is returned only once, in this response, and cannot be retrieved again.", "operationId": "create-api-token", "tags": [ "API Tokens" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/api_token_create" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_token": { "allOf": [ { "$ref": "#/components/schemas/ApiToken" }, { "type": "object", "properties": { "token": { "type": "string", "description": "The plaintext API token. Only returned on creation; store it securely.", "readOnly": true, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." } } } ] } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/api_tokens/{api_token_id}": { "parameters": [ { "$ref": "#/components/parameters/api_token_id" } ], "delete": { "summary": "Revoke API Token", "description": "Revokes an API token so it can no longer be used.", "operationId": "delete-api-token", "tags": [ "API Tokens" ], "security": [ { "AuthKey": [] } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/administrators": { "get": { "summary": "List Administrators", "operationId": "list-administrators", "tags": [ "Administrators" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrators": { "type": "array", "items": { "$ref": "#/components/schemas/Administrator" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/administrators" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create Administrator", "description": "Creates a new administrator, or restores access to a revoked/deleted one.", "operationId": "create-administrator", "tags": [ "Administrators" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/administrator_create_update" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrator": { "$ref": "#/components/schemas/Administrator" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/administrators/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "Get Administrator Details", "description": "Gets details of an administrative user", "operationId": "get-administrator", "tags": [ "Administrators" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrator": { "$ref": "#/components/schemas/Administrator" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } }, "patch": { "summary": "Update Administrator", "description": "Updates an administrator's details", "operationId": "update-administrator", "tags": [ "Administrators" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/administrator_create_update" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrator": { "$ref": "#/components/schemas/Administrator" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } }, "delete": { "summary": "Revoke Administrator Access", "description": "Revokes all access from an administrator", "operationId": "revoke-administrator", "tags": [ "Administrators" ], "security": [ { "AuthKey": [] } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/downloads": { "get": { "summary": "List Downloads", "description": "Lists all downloads", "operationId": "list-downloads", "tags": [ "Downloads" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/downloaded_at_from" }, { "$ref": "#/components/parameters/downloaded_at_to" }, { "$ref": "#/components/parameters/family" }, { "$ref": "#/components/parameters/user_ids" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "downloads": { "type": "array", "description": "List of downloads matching the query", "items": { "$ref": "#/components/schemas/Download" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/downloads" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/downloads/totals_by_day": { "get": { "summary": "Daily Download Totals", "description": "Returns aggregate download counts grouped by day for the requested date range (up to two years). Totals include Spotify downloads when Spotify analytics data is available for the network.", "operationId": "list-downloads-totals-by-day", "parameters": [ { "$ref": "#/components/parameters/downloaded_at_from" }, { "$ref": "#/components/parameters/downloaded_at_to" }, { "$ref": "#/components/parameters/family" }, { "$ref": "#/components/parameters/feed_id_query" } ], "tags": [ "Downloads" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_totals_by_day": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The calendar date (UTC) for the download total.", "readOnly": true, "example": "2024-01-15" }, "network_id": { "description": "The network id. Only returned when the family parameter is set.", "readOnly": true, "example": 1198153629 }, "total": { "type": "integer", "description": "Total downloads on this date, including Spotify when available.", "readOnly": true, "example": 1267 } } } } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/downloads/totals": { "get": { "summary": "Cumulative User Downloads", "description": "Returns a cumulative tally of episodes downloaded by users", "operationId": "list-downloads-totals", "parameters": [ { "$ref": "#/components/parameters/family" }, { "$ref": "#/components/parameters/updated_since_required" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "tags": [ "Downloads" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_totals": { "type": "array", "items": { "type": "object", "properties": { "first_download_date": { "type": "string", "format": "date", "description": "The first date the user downloaded an episode.", "readOnly": true, "example": "2011-04-20" }, "last_download_date": { "type": "string", "format": "date", "description": "The most recent date the user has downloaded an episode.", "readOnly": true, "example": "2011-04-20" }, "network_id": { "description": "The id of the user's network. Only returned when family parameter is set.", "readOnly": true, "example": 1198153629 }, "total": { "type": "integer", "description": "Total cumulative episodes downloaded by the user.", "readOnly": true, "example": 126771896 }, "user_id": { "type": "integer", "description": "The id of the user.", "readOnly": true, "example": 208583604 } } } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/downloads/totals" } } } ] } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/episodes": { "get": { "summary": "List Episodes", "description": "Lists all episodes", "operationId": "list-episodes", "tags": [ "Episodes" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/feed_ids" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "episodes": { "type": "array", "description": "List of episodes matching the query", "items": { "$ref": "#/components/schemas/Episode" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMetadata" } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/posts": { "get": { "summary": "List Posts", "description": "Lists published posts for the network, most recent first. Drafts and scheduled posts that are not yet live are never returned.", "operationId": "list-posts", "tags": [ "Posts" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/published_from" }, { "$ref": "#/components/parameters/published_to" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/tag" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "description": "List of posts matching the query", "items": { "$ref": "#/components/schemas/Post" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMetadata" } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/posts/{slug}": { "get": { "summary": "Get post details", "description": "Gets a single published post by slug. If the slug is one the post used previously, responds 301 with the current slug so the caller can redirect the reader.", "operationId": "get-post", "tags": [ "Posts" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "$ref": "#/components/schemas/Post" } } } } } }, "301": { "description": "Moved Permanently. The requested slug has been retired; use the current slug provided here to build your URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect": { "type": "object", "properties": { "slug": { "type": "string", "example": "my-first-post" } } } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/feeds": { "get": { "summary": "List Feeds", "description": "Lists all feeds", "operationId": "list-feeds", "tags": [ "Feeds" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeds": { "type": "array", "description": "List of feeds matching the query", "items": { "$ref": "#/components/schemas/Feed" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/feeds" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create a Feed", "description": "Creates a new feed", "operationId": "create-feed", "tags": [ "Feeds" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/feed_create" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "episode": { "type": "object", "description": "The created episode", "$ref": "#/components/schemas/Feed" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "description": "The parameter-specific errors." }, "message": { "type": "string", "example": "The given data is invalid" } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/feeds/{feed_id}": { "get": { "summary": "Get feed details", "parameters": [ { "$ref": "#/components/parameters/feed_id" } ], "description": "Gets details on a single feed", "operationId": "get-feed", "tags": [ "Feeds" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "feed": { "$ref": "#/components/schemas/Feed" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } }, "patch": { "summary": "Update Feed", "parameters": [ { "$ref": "#/components/parameters/feed_id" } ], "description": "Updates an existing feed", "operationId": "update-feed", "tags": [ "Feeds" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/feed_update" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/Feed" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } }, "delete": { "summary": "Delete Feed", "parameters": [ { "$ref": "#/components/parameters/feed_id" } ], "description": "Removes a feed entirely, including from user's libraries", "operationId": "delete-feed", "tags": [ "Feeds" ], "security": [ { "AuthKey": [] } ], "responses": { "204": { "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body" } } }, "description": "No Content" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users": { "get": { "summary": "List Users", "description": "Lists all users", "operationId": "list-users", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "description": "List of users matching the query", "items": { "$ref": "#/components/schemas/User" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/users" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create user", "description": "Creates a new user. Subscriptions and one-time purchases are created separately.", "operationId": "create-user", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/user_create_update" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/users/search": { "post": { "summary": "Search users", "description": "Searches all users by email address or external ID", "operationId": "search-users", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/user_search_include" }, { "$ref": "#/components/parameters/per_page" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The user's email address", "example": "user@example.com", "format": "email" }, "external_id": { "type": "string", "description": "The external id of the member", "example": "b990a4b9-ca60-4c02-b1d0-357b0ba632b6" }, "family": { "type": "string", "description": "Defines which related networks to include in the results:\n* 'all' - Include all related networks\n* 'children' - Only include child networks\n* Comma separated list of specific related network IDs\n", "example": "all" }, "login_token": { "type": "string", "description": "Valid login token for an audience member", "example": "eyJ0IjoibCIsImMiOiIxMjMiLCJ1IjoiMTIzIiwiZCI6IjE3Nzg2ODg3NzQiLCJlIjoxNzc4Njg4Nzc0XCwiayI6MX18MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "description": "List of users matching the search", "items": { "$ref": "#/components/schemas/UserSearch" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/users/search" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "Get user details", "description": "Gets details on a single user", "operationId": "get-user", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } }, "patch": { "summary": "Update user", "description": "Updates a user", "operationId": "update-user", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/user_create_update" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/login_token": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "Get User Login Token", "description": "Gets a login token for a user", "operationId": "get-user-token", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/send_login_email": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Send User Login Email", "description": "Sends the user a login email including an auth link.", "operationId": "send-user-login-email", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "format": "url", "description": "A URL the user will be redirected to after authentication is complete." } } } } } }, "responses": { "202": { "description": "Request accepted, and email will be sent momentarily. No content included in response.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body" } } } }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/send_welcome_email": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Send User a Welcome Email", "description": "Sends a new user a welcome email including an auth link.", "operationId": "send-user-welcome-email", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "202": { "description": "Request accepted, and email will be sent momentarily. No content included in response.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body" } } } }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/forget": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Forget User", "description": "Permanently deletes or anonymizes the user's personal data, e.g. for GDPR right to erasure (\"right to be forgotten\") requests. The work is queued and completes shortly after the response. The user is not emailed. This cannot be undone. Repeating the request for an already forgotten user is accepted and has no further effect. Users with an active Stripe-billed subscription must have it cancelled first; any other active subscriptions are cancelled automatically.", "operationId": "forget-user", "tags": [ "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "202": { "description": "Request accepted, and the user will be forgotten momentarily. No content included in response.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body" } } } }, "404": { "description": "Not Found" }, "409": { "description": "Conflict, the user has an active Stripe-billed subscription which must be cancelled first.", "$ref": "#/components/responses/ErrorResponse" } } } }, "/users/{user_id}/subscriptions": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "List User Subscriptions", "description": "Lists all subscriptions for a user", "operationId": "list-user-subscriptions", "tags": [ "Subscriptions", "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "description": "List of the user's subscriptions", "items": { "$ref": "#/components/schemas/Subscription" } } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/purchases": { "get": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "summary": "List User's One-Time Purchases", "description": "Lists all one-time purchases for a user", "operationId": "list-user-purchases", "tags": [ "Purchases", "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "description": "List of the user's one-time purchases", "items": { "$ref": "#/components/schemas/Purchase" } } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/feeds": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "List User Feeds", "description": "Lists feeds accessible to the user, including personalized URLs for podcasting apps", "operationId": "list-user-feeds", "tags": [ "Users", "Feeds" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeds": { "type": "array", "description": "List of the user's feeds", "items": { "$ref": "#/components/schemas/UserFeed" } } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/feeds/{feed_id}": { "parameters": [ { "$ref": "#/components/parameters/user_id" }, { "$ref": "#/components/parameters/feed_id" } ], "get": { "summary": "Get User Feed", "description": "Gets details of a specific feed that the user may access", "operationId": "get-user-feed", "tags": [ "Users", "Feeds" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "feed": { "$ref": "#/components/schemas/UserFeed" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/users/{user_id}/feeds/{feed_id}/send_setup_sms": { "parameters": [ { "$ref": "#/components/parameters/user_id" }, { "$ref": "#/components/parameters/feed_id" } ], "post": { "summary": "Send User SMS Link", "description": "Sends the user an SMS message with a link to set up the given feed.", "operationId": "send-feed-setup-sms", "tags": [ "Users", "Feeds" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "The phone number to send the SMS to.", "example": "+15555555555" } } } } } }, "responses": { "202": { "description": "Request accepted, and SMS will be sent momentarily. No content included in response." }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" }, "503": { "description": "Service Unavailable" } } } }, "/subscriptions": { "get": { "summary": "List Subscriptions", "description": "Lists all subscriptions", "operationId": "list-subscriptions", "tags": [ "Subscriptions" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/subscription_status" }, { "$ref": "#/components/parameters/subscription_plan_ids" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "description": "List of subscriptions matching the query", "items": { "$ref": "#/components/schemas/Subscription" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/subscriptions" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create a subscription", "description": "Creates a new active subscription for a user", "operationId": "create-subscription", "tags": [ "Users", "Subscriptions" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ends_at": { "description": "Optionally set date when access expires", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "subscription_price_id": { "type": "integer", "description": "Unique identifier of the subscription price associated with the subscription.", "example": 987654 }, "user_id": { "type": "integer", "description": "Unique identifier of the user.", "example": 123456 } }, "required": [ "subscription_price_id", "user_id" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/subscriptions/{subscription_id}": { "patch": { "parameters": [ { "$ref": "#/components/parameters/subscription_id" } ], "summary": "Update Subscription", "description": "Updates a subscription", "operationId": "update-subscription", "tags": [ "Subscriptions" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ends_at": { "description": "Optionally set date when access expires", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "Active", "Cancelled" ] }, "autorenew": { "type": "boolean", "description": "Whether the subscription is set to auto-renew. Only allowed when the subscription is connected to an existing payment method in Supporting Cast." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } }, "delete": { "parameters": [ { "$ref": "#/components/parameters/subscription_id" } ], "summary": "Cancel Subscription", "description": "Cancels a user's subscription", "operationId": "cancel-subscription", "tags": [ "Subscriptions", "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/purchases": { "get": { "summary": "List User Purchases", "description": "Lists all user one time purchases", "operationId": "list-purchases", "tags": [ "Purchases" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/product_ids" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "description": "List of user one time purchases matching the query", "items": { "$ref": "#/components/schemas/Purchase" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/purchases" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create One Time Purchase", "description": "Creates a one time purchase for a user", "operationId": "create-purchase", "tags": [ "Purchases", "Users" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Unique identifier of the product purchased.", "example": 987654 }, "user_id": { "type": "integer", "description": "Unique identifier of the user.", "example": 123456 } }, "required": [ "product_id", "user_id" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "$ref": "#/components/schemas/Purchase" } } } } } }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/purchases/{purchase_id}": { "parameters": [ { "$ref": "#/components/parameters/purchase_id" } ], "delete": { "summary": "Delete User One-Time Purchase", "description": "Removes a user's access to a one-time purchase", "operationId": "delete-purchase", "tags": [ "Purchases", "Users" ], "security": [ { "AuthKey": [] } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } }, "/security_events": { "get": { "summary": "List Security Events", "description": "Returns the network's security events oldest first, for ingestion into your own logging or SIEM system. Covers authentication, changes to users and roles, changes to API credentials, changes to security configuration, access to customer data, and alerts that may indicate a problem.\n\nEvents are available in real time and retained well beyond 90 days. For incremental retrieval, page forward with the `cursor` from `links.next` and resume from the last cursor you stored; `occurred_at_from` and `occurred_at_to` can bound a specific window. The `id` of each event is stable, so a replayed range can be deduplicated safely.\n\nThese events reference identifiers only. They never contain credentials, tokens, encryption keys, or personally identifiable information. Where an existing record was modified, `changed_fields` names the fields that changed without their values; it is empty for records that were created or deleted. Note that `outcome` is only ever `failure` for authentication events, since every other category records an action that already completed.\n\nA request covers at most 90 days. Send both `occurred_at_from` and `occurred_at_to` to choose the window; any 90 days are valid, however far back they start. Omit both and you get the last 90 days, send only `occurred_at_to` and you get the 90 days before it, and send only `occurred_at_from` and it runs to now, provided that is within 90 days. A window wider than 90 days, or an open-ended `occurred_at_from` further back than that, returns `422` rather than a partial answer. Back-fill history by stepping the window 90 days at a time, oldest first.", "operationId": "list-security-events", "tags": [ "Security Events" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/security_event_category" }, { "$ref": "#/components/parameters/occurred_at_from" }, { "$ref": "#/components/parameters/occurred_at_to" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "security_events": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityEvent" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/security_events" } } } ] } } } } } }, "422": { "description": "Unprocessable Entity" }, "429": { "description": "Too Many Requests" }, "503": { "description": "Service Unavailable. The requested range held too many events to serve within the server-side time limit. Narrow the window or resume from the last cursor, then retry." } } } }, "/subscription_plans": { "get": { "summary": "List Subscription Plans", "description": "Lists all subscription plans", "operationId": "list-subscription-plans", "tags": [ "Subscription Plans" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_plans": { "type": "array", "description": "List of subscription plans matching the query", "items": { "$ref": "#/components/schemas/SubscriptionPlan" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/subscription_plans" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } }, "post": { "summary": "Create a Subscription Plan", "description": "Creates a new subscription plan / audience", "operationId": "create-subscription-plan", "tags": [ "Subscription Plans" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the subscription plan / audience", "example": "Gold Club" }, "uuid": { "type": "string", "format": "uuid", "description": "Unique identifier", "example": "8cc7ac42-fd66-4157-a614-45dd130e324e" }, "visibility": { "example": "Public", "type": "string", "enum": [ "Private", "Public", "Unlisted" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_plan": { "$ref": "#/components/schemas/SubscriptionPlan" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/subscription_plans/{subscription_plan_id}": { "parameters": [ { "$ref": "#/components/parameters/subscription_plan_id" } ], "get": { "summary": "Get Subscription Plan", "description": "Gets details on a subscription plan", "operationId": "get-subscription-plan", "tags": [ "Subscription Plans" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_plan": { "$ref": "#/components/schemas/SubscriptionPlan" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } }, "patch": { "summary": "Update Subscription Plan", "description": "Updates a subscription plan / audience", "operationId": "update-subscription-plan", "tags": [ "Subscription Plans" ], "security": [ { "AuthKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the subscription plan / audience", "example": "Gold Club" }, "visibility": { "example": "Public", "type": "string", "enum": [ "Private", "Public", "Unlisted" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_plan": { "$ref": "#/components/schemas/SubscriptionPlan" } } } } } }, "422": { "description": "Unprocessable content", "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "Too Many Requests" } } } }, "/subscription_prices": { "get": { "summary": "List Subscription Prices", "description": "Lists all subscription prices", "operationId": "list-subscription-prices", "tags": [ "Subscription Prices" ], "security": [ { "AuthKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/subscription_plan_ids" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_prices": { "type": "array", "description": "List of subscription prices matching the query", "items": { "$ref": "#/components/schemas/SubscriptionPrice" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CursorPaginationMetadata" }, { "type": "object", "properties": { "path": { "example": "https://api.supportingcast.fm/v2/{network_id}/subscription_prices" } } } ] } } } } } }, "429": { "description": "Too Many Requests" } } } }, "/subscription_prices/{subscription_price_id}": { "parameters": [ { "$ref": "#/components/parameters/subscription_price_id" } ], "get": { "summary": "Get Subscription Price", "description": "Gets details on a subscription price", "operationId": "get-subscription-price", "tags": [ "Subscription Prices" ], "security": [ { "AuthKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_price": { "$ref": "#/components/schemas/SubscriptionPrice" } } } } } }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" } } } } }, "components": { "securitySchemes": { "AuthKey": { "type": "http", "description": "Please use a token from the API Tokens section of your admin console.", "name": "Authorization", "scheme": "bearer", "bearerFormat": "Bearer ", "in": "header" } }, "parameters": { "per_page": { "in": "query", "name": "per_page", "description": "Pagination parameter to set the number of results to return per request", "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "example": 20 } }, "cursor": { "in": "query", "name": "cursor", "description": "Pagination parameter indicating the item the search should start at", "schema": { "type": "string" } }, "api_token_id": { "name": "api_token_id", "in": "path", "description": "Unique identifier of the API token", "required": true, "schema": { "type": "integer", "example": 123456 } }, "updated_since": { "in": "query", "name": "updated_since", "description": "Filter results to only items updated on or after this date (UTC, in ISO-8601 format)", "schema": { "type": "string", "format": "date", "example": "2023-11-03T13:31:35" } }, "user_id": { "name": "user_id", "in": "path", "description": "Unique identifier of the user", "required": true, "schema": { "type": "integer", "example": 123456 } }, "downloaded_at_from": { "in": "query", "name": "downloaded_at_from", "description": "Filter results to only items downloaded on or after this date (UTC, in ISO-8601 format)", "schema": { "type": "string", "format": "date", "example": "2023-11-03T13:31:35" } }, "downloaded_at_to": { "in": "query", "name": "downloaded_at_to", "description": "Filter results to only items downloaded on or before this date (UTC, in ISO-8601 format)", "schema": { "type": "string", "format": "date", "example": "2023-11-03T13:31:35" } }, "family": { "in": "query", "name": "family", "description": "Defines which related networks to include in the results:\n* 'all' - Include all related networks\n* 'children' - Only include child networks\n* '1,2,3' - Include only the specified network IDs\n", "schema": { "type": "string", "example": "all" } }, "user_ids": { "name": "user_ids", "in": "query", "description": "Filter downloads to only those from specific users", "required": false, "schema": { "type": "string", "description": "Comma-separated list of user IDs", "example": "123,456,789" } }, "feed_id_query": { "in": "query", "name": "feed_id", "description": "Filter results to a single feed. Omit to include all feeds.", "schema": { "type": "integer", "example": 123456 } }, "updated_since_required": { "in": "query", "name": "updated_since", "description": "Filter results to only items updated on or after this date (UTC, in ISO-8601 format)", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2023-11-03T13:31:35" } }, "feed_ids": { "in": "query", "name": "feed_ids", "description": "List of feed IDs to filter by", "schema": { "type": "string", "example": "1,2,3" } }, "published_from": { "in": "query", "name": "published_from", "description": "Filter to posts published on or after this date (UTC, in ISO-8601 format)", "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, "published_to": { "in": "query", "name": "published_to", "description": "Filter to posts published on or before this date (UTC, in ISO-8601 format)", "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, "tag": { "in": "query", "name": "tag", "description": "Filter to posts tagged with this tag, by tag slug or name", "schema": { "type": "string", "example": "announcements" } }, "slug": { "name": "slug", "in": "path", "description": "A post's current slug, or any slug it previously used (retired slugs redirect to the current one)", "required": true, "schema": { "type": "string", "example": "my-first-post" } }, "feed_id": { "name": "feed_id", "in": "path", "description": "Unique identifier of the feed", "required": true, "schema": { "type": "integer", "example": 123456 } }, "user_search_include": { "name": "include", "in": "query", "description": "Comma separated list of additional included data fields. Limited to login_token", "required": false, "schema": { "type": "string", "example": "login_token" } }, "subscription_status": { "in": "query", "name": "subscription_status", "description": "Filter results to only subscriptions having this status", "schema": { "type": "string", "enum": [ "Active", "Alert", "Suspended", "Cancelled" ] } }, "subscription_plan_ids": { "in": "query", "name": "subscription_plan_ids", "description": "List of subscription plan IDs to filter by", "schema": { "type": "string", "example": "1,2,3" } }, "subscription_id": { "name": "subscription_id", "in": "path", "description": "Unique identifier of the subscription.", "required": true, "schema": { "type": "integer", "example": 123456 } }, "product_ids": { "in": "query", "name": "product_ids", "description": "List of product IDs to filter by", "schema": { "type": "string", "example": "1,2,3" } }, "purchase_id": { "name": "purchase_id", "in": "path", "description": "Unique identifier of the one time purchase.", "required": true, "schema": { "type": "integer", "example": 123456 } }, "security_event_category": { "in": "query", "name": "category", "description": "Comma separated list of categories to return. Defaults to all categories.
authentication — sign in, failed sign in, and sign out.principal — administrator, member, and role changes.credential — API token and signing key creation and revocation.security_configuration — network security settings, system settings, rate limits, and webhook subscriptions.data_access — bulk data exports, privileged support access, and member login links generated by an administrator.anomaly — alerts and system advisories that may indicate a problem.Hello world.
" }, { "type": "null" } ] }, "id": { "type": "integer", "description": "Unique identifier of the post.", "readOnly": true, "example": 123456 }, "published_at": { "type": "string", "format": "date-time", "description": "The time the post was published." }, "slug": { "type": "string", "description": "The post's current URL slug, generated at publish time and stable across title edits.", "example": "my-first-post" }, "tags": { "type": "object", "description": "Tags applied to the post, keyed by tag slug with the tag name as the value.", "additionalProperties": { "type": "string" }, "example": { "announcements": "Announcements" } }, "teaser": { "description": "Teaser/excerpt for the post, suitable for list pages.", "oneOf": [ { "type": "string", "example": "A short teaser for the post." }, { "type": "null" } ] }, "teaser_image_url": { "description": "URL of the post's teaser image, if set.", "oneOf": [ { "type": "string", "format": "url", "example": "https://media.example.com/teaser.jpg" }, { "type": "null" } ] }, "title": { "type": "string", "description": "Publicly displayed title of the post.", "example": "My First Post" }, "updated_at": { "type": "string", "format": "date-time", "description": "The time the post was last updated.", "readOnly": true } } }, "Feed": { "title": "Feed", "type": "object", "description": "A feed representing a podcast, audiobook, season, or series.", "properties": { "author": { "type": "string", "description": "Creator(s) of the audiobook, podcast, season, series", "example": "Jane Doe" }, "created_at": { "type": "string", "format": "date-time", "description": "The time the episode was created in Supporting Cast.", "readOnly": true }, "complete": { "type": "boolean", "description": "Whether the feed will get new episodes in the future, or not." }, "description": { "type": "string", "description": "Publicly displayed description of the feed.", "example": "Lorem ipsum..." }, "email": { "description": "Address of the creators of this feed. Spotify relies on this to verify ownership.", "oneOf": [ { "type": "string", "example": "jane-doe@example.com" }, { "type": "null" } ] }, "explicit": { "description": "Whether content of feed is explicit or not.", "oneOf": [ { "type": "boolean", "example": true }, { "type": "string", "example": "Clean" }, { "type": "null" } ] }, "id": { "type": "integer", "description": "Unique identifier of the feed.", "readOnly": true, "example": 123456 }, "image_url": { "type": "string", "description": "URL of the feed art", "example": "https://image.example/image.jpg", "format": "url" }, "isbn": { "type": "string", "description": "ISBN of the underlying book, only for feeds of type 'Audiobook'.", "example": "978-0-306-40615-7", "readOnly": true }, "name": { "type": "string", "description": "Publicly displayed title of the feed.", "example": "Lorem Ipsum" }, "podcast_id": { "type": "integer", "description": "Legacy identifier of the feed, to help with transition from `/v1/podcasts` API.", "readOnly": true, "example": 123456 }, "sort_type": { "description": "Whether episodes should be played back in chronological or most-to-least recent order.", "oneOf": [ { "type": "string", "example": "Episodic" }, { "type": "string", "example": "Serial" }, { "type": "null" } ] }, "source_type": { "description": "Where new content, if any, comes from.", "example": "Third Party RSS", "oneOf": [ { "type": "string", "example": "ONIX", "readOnly": true }, { "type": "string", "example": "Supporting Cast" }, { "type": "string", "example": "Third Party RSS" }, { "type": "null" } ] }, "source_url": { "type": "string", "format": "url", "description": "The source URL that is polled for changes, or was imported from, if any.", "example": "https://non-supportingcast-host.example/uuid/file.rss" }, "type": { "description": "Feed classification, i.e. what kind of content it includes.", "oneOf": [ { "type": "string", "example": "Audiobook", "readOnly": true }, { "type": "string", "example": "Podcast" }, { "type": "string", "example": "Season" }, { "type": "string", "example": "Series" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The time the episode was last updated in Supporting Cast.", "readOnly": true }, "uuid": { "description": "Unique identifier for the feed.", "oneOf": [ { "type": "string", "example": "ec53210b-26c4-44d8-bcef-f7336b13217f" }, { "type": "null" } ] } } }, "User": { "title": "User", "type": "object", "description": "A user in a network", "properties": { "id": { "type": "integer", "description": "Unique identifier of the user.", "readOnly": true, "example": 123456 }, "account_type": { "description": "Type of account the user has (Stripe Subscriptionor Purchase, Gift, Invite, etc.).", "type": "string", "enum": [ "API", "Audiobook Card Purchaser", "Free Subscription", "Gift", "Invite", "Single Sign On", "Stripe Subscription or Purchase" ], "readOnly": true }, "email": { "description": "Email address associated with the user.", "oneOf": [ { "type": "string", "format": "email", "example": "user@example.com" }, { "type": "null" } ] }, "external_id": { "description": "External identifier for the user.", "oneOf": [ { "type": "string", "example": "fefcc778-d282-4497-bffb-ca60ab7f5d1c" }, { "type": "null" } ] }, "first_name": { "description": "The user's first name.", "oneOf": [ { "type": "string", "example": "Alice" }, { "type": "null" } ] }, "first_http_referer": { "description": "The first HTTP referer of the user.", "oneOf": [ { "type": "string", "example": "https://www.google.com" }, { "type": "null" } ] }, "first_landing_url": { "description": "The first landing URL of the user.", "oneOf": [ { "type": "string", "example": "https://www.google.com" }, { "type": "null" } ] }, "first_promo_code": { "description": "The first promo code of the user.", "oneOf": [ { "type": "string", "example": "PROMO123" }, { "type": "null" } ] }, "first_utm_campaign": { "description": "The first UTM campaign of the user.", "oneOf": [ { "type": "string", "example": "utm_campaign" }, { "type": "null" } ] }, "first_utm_content": { "description": "The first UTM content of the user.", "oneOf": [ { "type": "string", "example": "utm_content" }, { "type": "null" } ] }, "first_utm_medium": { "description": "The first UTM medium of the user.", "oneOf": [ { "type": "string", "example": "utm_medium" }, { "type": "null" } ] }, "first_utm_source": { "description": "The first UTM source of the user.", "oneOf": [ { "type": "string", "example": "utm_source" }, { "type": "null" } ] }, "first_utm_term": { "description": "The first UTM term of the user.", "oneOf": [ { "type": "string", "example": "utm_term" }, { "type": "null" } ] }, "last_name": { "description": "The user's last name.", "oneOf": [ { "type": "string", "example": "Testerson" }, { "type": "null" } ] }, "network_id": { "type": "integer", "description": "Unique identifier of the user's network", "readOnly": true, "example": 123456 }, "source": { "description": "How the user initiated the subscription.", "type": "string", "enum": [ "Sign-up", "Invite", "API", "Gift", "Audiobook Card", "Single Sign On" ], "readOnly": true }, "created_at": { "description": "Date and time the user joined", "type": "string", "format": "date-time", "readOnly": true }, "custom_1": { "description": "Optional custom data associated with the user.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_2": { "description": "Optional custom data associated with the user.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "UserSearch": { "title": "User", "type": "object", "description": "A user in a network", "properties": { "id": { "type": "integer", "description": "Unique identifier of the user.", "readOnly": true, "example": 123456 }, "email": { "description": "Email address associated with the user.", "oneOf": [ { "type": "string", "format": "email", "example": "user@example.com" }, { "type": "null" } ] }, "external_id": { "description": "External identifier for the user.", "oneOf": [ { "type": "string", "example": "fefcc778-d282-4497-bffb-ca60ab7f5d1c" }, { "type": "null" } ] }, "first_name": { "description": "The user's first name.", "oneOf": [ { "type": "string", "example": "Alice" }, { "type": "null" } ] }, "first_http_referer": { "description": "The first HTTP referer of the user.", "oneOf": [ { "type": "string", "example": "https://www.google.com" }, { "type": "null" } ] }, "first_landing_url": { "description": "The first landing URL of the user.", "oneOf": [ { "type": "string", "example": "https://www.google.com" }, { "type": "null" } ] }, "first_promo_code": { "description": "The first promo code of the user.", "oneOf": [ { "type": "string", "example": "PROMO123" }, { "type": "null" } ] }, "first_utm_campaign": { "description": "The first UTM campaign of the user.", "oneOf": [ { "type": "string", "example": "utm_campaign" }, { "type": "null" } ] }, "first_utm_content": { "description": "The first UTM content of the user.", "oneOf": [ { "type": "string", "example": "utm_content" }, { "type": "null" } ] }, "first_utm_medium": { "description": "The first UTM medium of the user.", "oneOf": [ { "type": "string", "example": "utm_medium" }, { "type": "null" } ] }, "first_utm_source": { "description": "The first UTM source of the user.", "oneOf": [ { "type": "string", "example": "utm_source" }, { "type": "null" } ] }, "first_utm_term": { "description": "The first UTM term of the user.", "oneOf": [ { "type": "string", "example": "utm_term" }, { "type": "null" } ] }, "last_name": { "description": "The user's last name.", "oneOf": [ { "type": "string", "example": "Testerson" }, { "type": "null" } ] }, "login_token": { "type": "string" }, "network_id": { "type": "integer", "description": "Unique identifier of the user's network", "readOnly": true, "example": 123456 }, "source": { "description": "How the user initiated the subscription.", "type": "string", "enum": [ "Sign-up", "Invite", "API", "Gift", "Audiobook Card", "Single Sign On" ], "readOnly": true }, "created_at": { "description": "Date and time the user joined", "type": "string", "format": "date-time", "readOnly": true }, "custom_1": { "description": "Optional custom data associated with the user.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_2": { "description": "Optional custom data associated with the user.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "Subscription": { "title": "Subscription", "type": "object", "description": "A subscription for a plan in a network", "properties": { "id": { "type": "integer", "description": "Unique identifier of the subscription.", "readOnly": true, "example": 123456 }, "user_id": { "type": "integer", "description": "Unique identifier of the user associated with the subscription.", "example": 654321 }, "subscription_price_id": { "type": "integer", "description": "Unique identifier of the subscription price associated with the subscription.", "example": 987654 }, "subscription_plan_id": { "type": "integer", "description": "Unique identifier of the subscription plan associated with the subscription.", "example": 456789 }, "subscription_plan": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the subscription plan associated with the subscription.", "example": "Basic Plan" } } }, "status": { "type": "string", "enum": [ "Active", "Alert", "Suspended", "Cancelled" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "The date the subscription was created on.", "readOnly": true }, "ends_at": { "type": "string", "format": "date-time", "description": "The date the subscription is scheduled to end." }, "free_trial": { "type": "boolean", "description": "Whether the subscription is in a free trial." }, "autorenew": { "type": "boolean", "description": "Whether the subscription is set to auto-renew." }, "source": { "description": "How the user initiated the subscription.", "type": "string", "enum": [ "Sign-up", "Invite", "API", "Gift", "Audiobook Card", "Single Sign On" ], "readOnly": true }, "http_referer": { "type": "string", "description": "The HTTP referer of the order that created this subscription." }, "landing_url": { "type": "string", "description": "The landing URL of the order that created this subscription." }, "promo_code": { "type": "string", "description": "The promo code of the order that created this subscription." }, "utm_campaign": { "type": "string", "description": "The UTM campaign of the order that created this subscription." }, "utm_content": { "type": "string", "description": "The UTM content of the order that created this subscription." }, "utm_medium": { "type": "string", "description": "The UTM medium of the order that created this subscription." }, "utm_source": { "type": "string", "description": "The UTM source of the order that created this subscription." }, "utm_term": { "type": "string", "description": "The UTM term of the order that created this subscription." } } }, "Purchase": { "title": "User Product", "type": "object", "description": "A user's one time purchase", "properties": { "id": { "type": "integer", "description": "Unique identifier of the purchase.", "readOnly": true, "example": 123456 }, "created_at": { "type": "string", "format": "date-time", "description": "The date access to the product was granted to the user.", "readOnly": true }, "product_id": { "type": "integer", "description": "Unique identifier of the purchase.", "readOnly": true, "example": 123456 }, "product": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the product", "example": "Season Pass" } } }, "order_id": { "type": "integer", "description": "The order ID that created this purchase.", "readOnly": true }, "user_id": { "type": "integer", "description": "Unique identifier of the user connected to the purchase.", "example": 123456 }, "http_referer": { "type": "string", "description": "The HTTP referer of the order that created this purchase." }, "landing_url": { "type": "string", "description": "The landing URL of the order that created this purchase." }, "promo_code": { "type": "string", "description": "The promo code of the order that created this purchase." }, "utm_campaign": { "type": "string", "description": "The UTM campaign of the order that created this purchase." }, "utm_content": { "type": "string", "description": "The UTM content of the order that created this purchase." }, "utm_medium": { "type": "string", "description": "The UTM medium of the order that created this purchase." }, "utm_source": { "type": "string", "description": "The UTM source of the order that created this purchase." }, "utm_term": { "type": "string", "description": "The UTM term of the order that created this purchase." } } }, "UserFeed": { "title": "User Feed", "type": "object", "description": "Feed details including user specific access URLs.", "readOnly": true, "properties": { "id": { "type": "integer", "description": "Unique identifier of the feed.", "example": 123456 }, "name": { "type": "string", "description": "The name of the feed." }, "url": { "type": "string", "format": "url", "description": "The user specific URL for the feed.", "example": "https://mynetwork.supportingcast.fm/content/er24343q4f....rss" }, "description": { "type": "string", "description": "Description of the feed.", "example": "My Show is the best podcast. This is our exclusive members-only version, with no ads." }, "image_url": { "type": "string", "format": "url", "description": "The URL of the feed’s tile image." }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string", "description": "Identifier of the app.", "example": "apple_podcasts" }, "name": { "type": "string", "description": "Name of the app.", "example": "Apple Podcasts" }, "url": { "type": "string", "format": "url", "description": "The user specific deep link URL for the feed to load this app.", "example": "podcast://example.supportingcast.fm/content/eyJ0IjoicCIsImMiOiI1NiIsInUiOiI0MSIsImQiOiIxNzQ3ODQ0NjY4IiwiayI6MTB9fGVjYzMyMjdhZDVkNzI4ZTMyMmQ1MzNiODM5NmFjYzVlZmVkN2QyYjAxODYzYjIzNjQ1ZGFlZTZhM2FiM2VjM2U.rss" } } } } } }, "SecurityEvent": { "title": "Security Event", "type": "object", "description": "A single security-relevant event. Events reference identifiers only: they never contain credentials, tokens, encryption keys, or personally identifiable information. Where a record was changed, the names of the changed fields are reported without their values.", "properties": { "id": { "type": "string", "description": "Unique, stable identifier for the event, safe to use for deduplication when replaying a time range.", "readOnly": true, "example": "audit_log:1234567" }, "action": { "type": "string", "description": "The action performed, as `category.verb`.", "example": "credential.created" }, "actor": { "description": "Who or what performed the action. Null when nothing identifies the actor, such as a failed sign in for an address that isn't recognized.", "oneOf": [ { "type": "object", "required": [ "id", "type" ], "properties": { "api_token_id": { "type": "integer", "description": "The API token used. Present only when the action came through the API; omitted entirely otherwise.", "example": 99 }, "id": { "description": "Identifier of the acting user. Null only in the rare case of an API token whose owning user no longer exists, in which case `api_token_id` identifies the actor.", "oneOf": [ { "type": "integer", "example": 42 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "user", "api_token" ], "example": "user" } } }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "authentication", "principal", "credential", "security_configuration", "data_access", "anomaly" ], "example": "credential" }, "changed_fields": { "type": "array", "description": "Names of the fields that changed, without their values. Only reported for actions that modified an existing record; this is always empty when a record was created or deleted, since every field is involved and the names would say nothing about what was done.", "items": { "type": "string" }, "example": [ "revoked" ] }, "network_id": { "type": "integer", "description": "The network the event belongs to.", "example": 5 }, "object": { "description": "What was accessed or modified. Null when the event names nothing that was acted on, such as a failed sign in for an address that isn't recognized.", "oneOf": [ { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "oneOf": [ { "type": "integer", "example": 77 }, { "type": "null" } ] }, "type": { "description": "The kind of record acted on, such as `user`, `role`, `token`, or `network`.", "oneOf": [ { "type": "string", "example": "token" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (UTC, ISO-8601).", "example": "2026-08-14T12:34:56Z" }, "outcome": { "type": "string", "description": "Whether the action succeeded. Only authentication events can report `failure`; every other category records actions that already completed.", "enum": [ "success", "failure" ], "example": "success" }, "source_ip": { "description": "IP address the action originated from.", "oneOf": [ { "type": "string", "example": "203.0.113.4" }, { "type": "null" } ] } } }, "SubscriptionPlan": { "title": "SubscriptionPlan", "type": "object", "description": "A subscription plan (a.k.a. 'Audience') within a network. These represent entitlements or tiers granting users access to feeds and other features.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the subscription plan.", "example": 123456, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "The date the subscription plan was created.", "readOnly": true }, "name": { "type": "string", "example": "Gold Club", "description": "The name of the subscription plan / audience." }, "uuid": { "type": "string", "format": "uuid", "example": "8cc7ac42-fd66-4157-a614-45dd130e324e" }, "visibility": { "description": "Kinds of audience that can see the subscription plan.", "example": "Public", "type": "string", "enum": [ "Private", "Public", "Unlisted" ] } } }, "SubscriptionPrice": { "title": "SubscriptionPrice", "type": "object", "description": "A price option attached to a subscription plan / audience. Represents what listeners pay (or 'free') and at what cadence to access the plan.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the subscription price.", "example": 234567, "readOnly": true }, "amount": { "type": [ "integer", "null" ], "description": "Price in the smallest unit of the currency (e.g. cents for USD). `null` for free prices.", "example": 999 }, "currency": { "type": [ "string", "null" ], "description": "ISO-4217 currency code, lowercased. `null` for free prices.", "example": "usd" }, "interval": { "type": [ "string", "null" ], "description": "Billing cadence of the price. `null` for free prices.", "example": "month", "enum": [ "day", "week", "month", "year", null ] }, "pwyw": { "type": "boolean", "description": "Whether this price is a pay-what-you-want offering. The amount shown is the suggested/template amount; the listener may choose a different amount at checkout.", "example": false }, "subscription_plan_id": { "type": "integer", "description": "ID of the subscription plan / audience.", "example": 123456, "readOnly": true } } } }, "requestBodies": { "api_token_create": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Human-readable name of the token.", "maxLength": 255, "example": "My integration token" } } } } } }, "administrator_create_update": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The administrator's email address. Required if no external_id. Must be unique.", "example": "administrator@example.com", "format": "email" }, "external_id": { "type": "string", "description": "The administrator's external ID. Required if no email. Must be unique.", "example": "unique-identifier" }, "first_name": { "description": "The administrator's first name.", "type": "string", "example": "Jane" }, "last_name": { "description": "The administrator's last name.", "type": "string", "example": "Doe" } } } } } }, "feed_create": { "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": "string", "description": "Creator(s) of the audiobook, podcast, season, series", "example": "Jane Doe" }, "complete": { "type": "boolean" }, "description": { "type": "string", "description": "Public description of feed", "example": "Lorem ipsum..." }, "email": { "type": "string", "format": "email" }, "explicit": { "example": true, "oneOf": [ { "type": "boolean", "example": true }, { "type": "string", "example": "Clean" }, { "type": "null" } ] }, "image_url": { "type": "string", "description": "URL of the feed art", "example": "https://image.example/image.jpg", "format": "url" }, "isbn": { "type": "string", "description": "ISBN of the underlying book, only for feeds of type 'Audiobook'.", "example": "978-0-306-40615-7" }, "name": { "type": "string", "description": "The feed's name", "example": "Lorem Ipsum..." }, "private": { "type": "boolean", "description": "Whether feed is meant only for current audience members. Defaults to true.", "example": true }, "sort_type": { "example": "Serial", "oneOf": [ { "type": "string", "example": "Episodic" }, { "type": "string", "example": "Serial" }, { "type": "null" } ] }, "source_type": { "example": "Third Party RSS", "oneOf": [ { "type": "string", "example": "Supporting Cast" }, { "type": "string", "example": "Third Party RSS" }, { "type": "null" } ] }, "source_url": { "type": "string", "example": "https://non-supportingcast-host.example/uuid/file.rss", "format": "url" }, "type": { "example": "Audiobook", "oneOf": [ { "type": "string", "example": "Audiobook", "readonly": true }, { "type": "string", "example": "Podcast" }, { "type": "string", "example": "Season" }, { "type": "string", "example": "Series" }, { "type": "null" } ] }, "uuid": { "type": "string", "format": "uuid" } } } } } }, "feed_update": { "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": "string", "description": "Creator(s) of the audiobook, podcast, season, series", "example": "Jane Doe" }, "complete": { "type": "boolean" }, "description": { "type": "string", "description": "Public description of feed", "example": "Lorem ipsum..." }, "email": { "type": "string", "format": "email" }, "explicit": { "example": true, "oneOf": [ { "type": "boolean", "example": true }, { "type": "string", "example": "Clean" }, { "type": "null" } ] }, "image_url": { "type": "string", "description": "URL of the feed art", "example": "https://image.example/image.jpg", "format": "url" }, "isbn": { "type": "string", "description": "ISBN of the underlying book, only for feeds of type 'Audiobook'.", "example": "978-0-306-40615-7" }, "name": { "type": "string", "description": "The feed's name", "example": "Lorem Ipsum..." }, "sort_type": { "example": "Serial", "oneOf": [ { "type": "string", "example": "Episodic" }, { "type": "string", "example": "Serial" }, { "type": "null" } ] }, "source_url": { "type": "string", "example": "https://non-supportingcast-host.example/uuid/file.rss", "format": "url" } } } } } }, "user_create_update": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The user's email address. Required if no external_id. Must be unique.", "example": "user@example.com", "format": "email" }, "external_id": { "type": "string", "description": "The user's external ID. Required if no email. Must be unique.", "example": "unique-identifier" }, "first_name": { "description": "The user's first name.", "type": "string", "example": "Alice" }, "last_name": { "description": "The user's last name.", "type": "string", "example": "Testerson" }, "custom_1": { "description": "Optional custom data associated with the user.", "type": "string" }, "custom_2": { "description": "Optional custom data associated with the user.", "type": "string" } } } } } } }, "responses": { "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "High level description of the error." }, "errors": { "type": "object", "description": "A list of all errors keyed by input field." } } } } } }