openapi: 3.1.0 info: version: 1.0.0 title: Castopod API license: name: AGPL v3 url: https://code.castopod.org/adaures/castopod/-/blob/develop/LICENSE.md paths: /podcasts: get: summary: Get all podcasts operationId: get-all-podcasts responses: "200": description: Successful operation content: application/json: schema: type: array items: $ref: "#/components/schemas/Podcast" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /podcasts/{podcastId}: parameters: - name: podcastId in: path description: The id of the podcast to retrieve required: true schema: type: integer format: int64 get: summary: Get podcast by ID description: Returns a single podcast operationId: get-podcast-by-id responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/Podcast" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /episodes: get: summary: Get all episodes operationId: get-all-episodes responses: "200": description: Object of episodes content: application/json: schema: type: "array" items: $ref: "#/components/schemas/Episode" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Add a new episode operationId: add-episode requestBody: description: Episode object that needs to be added required: true content: multipart/form-data: schema: $ref: "#/components/schemas/EpisodeCreateRequest" responses: "201": description: Episode created successfully content: application/json: schema: $ref: "#/components/schemas/Episode" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /episodes/{episodeId}: parameters: - name: episodeId in: path description: The id of the episode to retrieve required: true schema: type: integer format: int64 get: summary: Get episode by ID description: Returns a single episode operationId: get-episode-by-id responses: "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Episode" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /episodes/{episodeId}/publish: post: summary: Publish an episode operationId: publish-episode parameters: - name: episodeId in: path description: The id of the episode to publish required: true schema: type: integer format: int64 requestBody: description: Publish parameters required: true content: application/json: schema: $ref: "#/components/schemas/EpisodePublishRequest" responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/Episode" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" components: schemas: Podcast: type: object required: - id - guid - actor_id - handle - title - description_markdown - description_html - cover_id - language_code - category_id - owner_name - owner_email - type - is_blocked - is_completed - is_locked - is_published_on_hubs - created_by - updated_by - created_at - updated_at - feed_url properties: id: type: integer format: int64 guid: type: string maxLength: 36 actor_id: type: integer format: int64 handle: type: string maxLength: 32 title: type: string maxLength: 128 description_markdown: type: string description_html: type: string cover_id: type: integer format: int64 banner_id: type: integer format: int64 language_code: type: string maxLength: 2 category_id: type: integer format: int64 minimum: 1 parental_advisory: type: string enum: - clean - explicit owner_name: type: string maxLength: 128 owner_email: type: string maxLength: 255 publisher: type: string maxLength: 128 type: type: string enum: - episodic - serial copyright: type: string maxLength: 128 episode_description_footer_markdown: type: string episode_description_footer_html: type: string is_blocked: type: integer format: int32 enum: - 0 - 1 is_completed: type: integer format: int32 enum: - 0 - 1 is_locked: type: integer format: int32 enum: - 0 - 1 imported_feed_url: type: string maxLength: 512 new_feed_url: type: string maxLength: 512 location_name: type: string maxLength: 128 location_geo: type: string maxLength: 32 location_osm: type: string maxLength: 12 custom_rss: type: string is_published_on_hubs: type: integer format: int32 enum: - 0 - 1 partner_id: type: string maxLength: 32 partner_link_url: type: string maxLength: 512 partner_image_url: type: string maxLength: 512 created_by: type: integer format: int64 updated_by: type: integer format: int64 created_at: type: object properties: date: type: string format: date-time timezone_type: type: integer format: int32 timezone: type: string updated_at: type: object properties: date: type: string format: date-time timezone_type: type: integer format: int32 timezone: type: string feed_url: type: string Episode: type: object required: - id - title - slug - podcast_id - created_by - updated_by - created_at - updated_at properties: id: type: integer format: int64 title: type: string slug: type: string podcast_id: type: integer format: int64 description_markdown: type: string description_html: type: string audio_url: type: string format: uri cover_url: type: string format: uri duration: type: integer format: int32 published_at: type: string format: date-time created_by: type: integer format: int64 updated_by: type: integer format: int64 EpisodeCreateRequest: type: object required: - user_id - updated_by - title - slug - podcast_id - audio_file properties: user_id: type: integer format: int64 description: ID of the user creating the episode updated_by: type: integer format: int64 description: ID of the user updating the episode title: type: string description: Title of the episode slug: type: string description: URL-friendly slug of the episode podcast_id: type: integer format: int64 description: ID of the podcast the episode belongs to audio_file: type: string format: binary description: Audio file for the episode cover: type: string format: binary description: Cover image for the episode description: type: string description: Description of the episode location_name: type: string description: Location associated with the episode parental_advisory: type: string enum: - clean - explicit description: Parental advisory rating episode_number: type: integer format: int32 description: Episode number (for serial podcasts) season_number: type: integer format: int32 description: Season number (for serial podcasts) type: type: string enum: - full - trailer - bonus description: Type of episode block: type: string enum: - "yes" - "no" description: Block episode from being published custom_rss: type: string description: Custom RSS content premium: type: string enum: - "yes" - "no" description: Mark episode as premium content transcript-choice: type: string enum: - upload-file - remote-url description: Transcript source choice transcript_file: type: string format: binary description: Transcript file transcript_remote_url: type: string format: uri description: Remote URL for transcript chapters-choice: type: string enum: - upload-file - remote-url description: Chapters source choice chapters_file: type: string format: binary description: Chapters file chapters_remote_url: type: string format: uri description: Remote URL for chapters EpisodePublishRequest: type: object required: - publication_method properties: publication_method: type: string enum: - now - schedule - with_podcast description: Method of publication scheduled_publication_date: type: string format: date-time description: Scheduled date and time for publication client_timezone: type: string description: Timezone of the client Error: type: object properties: status: type: integer format: int32 error: type: integer format: int32 messages: type: object properties: error: type: string