{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Castopod podcasts"
},
"paths": {
"/api/rest/v1/podcasts": {
"get": {
"summary": "List all podcasts",
"responses": {
"200": {
"description": "Object of podcasts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcasts"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/podcasts/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the podcast to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific podcast",
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcast"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes": {
"get": {
"summary": "List all episodes",
"responses": {
"200": {
"description": "Object of episodes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episodes"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new 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"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific episode",
"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"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}/publish": {
"post": {
"summary": "Publish an episode",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to publish",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"requestBody": {
"description": "Publish parameters",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpisodePublishRequest"
}
}
}
},
"responses": {
"200": {
"description": "Episode published successfully",
"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",
"minimum": 1,
"maxLength": 10
},
"guid": {
"type": "string",
"maxLength": 36
},
"actor_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"handle": {
"type": "string",
"maxLength": 32
},
"title": {
"type": "string",
"maxLength": 128
},
"description_markdown": {
"type": "string"
},
"description_html": {
"type": "string"
},
"cover_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"banner_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"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],
"minLength": 1
},
"is_completed": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"is_locked": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"imported_feed_url": {
"type": "string",
"maxLength": 512
},
"new_feed_url": {
"type": "string",
"maxLength": 512
},
"payment_pointer": {
"type": "string",
"maxLength": 128
},
"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],
"minLength": 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",
"minimum": 1,
"maxLength": 10
},
"updated_by": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"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"
}
}
},
"Podcasts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Podcast"
}
},
"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"
}
}
},
"Episodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Episode"
}
},
"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"
}
}
}
}
}
}
}
}