mirror of
https://code.castopod.org/adaures/castopod
synced 2025-05-14 10:15:46 +00:00
503 lines
12 KiB
YAML
503 lines
12 KiB
YAML
|
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
|