# List Podcasts by Publication URL

POST /api/v1/podcasts/by-url/
Content-Type: application/json

This endpoint returns a paginated list of podcasts. For GET requests, it returns the base podcast list. For POST requests, if the JSON body contains a 'url' parameter (representing the publication's custom URL), the view will filter the podcasts to return only those whose 'owner' matches the Publication owner's user. If the 'url' parameter is omitted, the full list is returned.

Reference: https://docs.aisquare.studio/api-reference/ai-square-studio-api/podcasts/by-url-list

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: AISquare Studio API
  version: 1.0.0
paths:
  /api/v1/podcasts/by-url/:
    post:
      operationId: by-url-create
      summary: List Podcasts by Publication URL
      description: >-
        This endpoint returns a paginated list of podcasts. For GET requests, it
        returns the base podcast list. For POST requests, if the JSON body
        contains a 'url' parameter (representing the publication's custom URL),
        the view will filter the podcasts to return only those whose 'owner'
        matches the Publication owner's user. If the 'url' parameter is omitted,
        the full list is returned.
      tags:
        - subpackage_podcasts
      responses:
        '200':
          description: >-
            A paginated list of podcasts. If a 'url' is provided in the POST
            body, only podcasts created by the corresponding Publication owner
            are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodcastList'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: >-
                    The custom URL of the publication used to filter the
                    podcasts.
components:
  schemas:
    LanguageEnum:
      type: string
      enum:
        - en
        - es
        - fr
        - de
        - it
        - pt
        - zh
        - ja
        - ko
        - ar
        - ru
        - hi
      description: |-
        * `en` - English
        * `es` - Spanish
        * `fr` - French
        * `de` - German
        * `it` - Italian
        * `pt` - Portuguese
        * `zh` - Chinese
        * `ja` - Japanese
        * `ko` - Korean
        * `ar` - Arabic
        * `ru` - Russian
        * `hi` - Hindi
      title: LanguageEnum
    BlankEnum:
      type: string
      enum:
        - ''
      title: BlankEnum
    NullEnum:
      description: Any type
      title: NullEnum
    PodcastListLanguage:
      oneOf:
        - $ref: '#/components/schemas/LanguageEnum'
        - $ref: '#/components/schemas/BlankEnum'
        - $ref: '#/components/schemas/NullEnum'
      description: |-
        Language for the podcast content (for future use)

        * `en` - English
        * `es` - Spanish
        * `fr` - French
        * `de` - German
        * `it` - Italian
        * `pt` - Portuguese
        * `zh` - Chinese
        * `ja` - Japanese
        * `ko` - Korean
        * `ar` - Arabic
        * `ru` - Russian
        * `hi` - Hindi
      title: PodcastListLanguage
    KnowledgeLevelEnum:
      type: string
      enum:
        - beginner
        - intermediate
        - advanced
        - expert
      description: |-
        * `beginner` - Beginner
        * `intermediate` - Intermediate
        * `advanced` - Advanced
        * `expert` - Expert
      title: KnowledgeLevelEnum
    GenerationStatusEnum:
      type: string
      enum:
        - not_started
        - generating_script
        - script_generated
        - generating_audio
        - completed
        - failed
      description: |-
        * `not_started` - Not Started
        * `generating_script` - Generating Script
        * `script_generated` - Script Generated
        * `generating_audio` - Generating Audio
        * `completed` - Completed
        * `failed` - Failed
      title: GenerationStatusEnum
    GlobalVisibilityEnum:
      type: string
      enum:
        - public
        - private
        - team
        - org
      description: |-
        * `public` - Public
        * `private` - Private
        * `team` - Team
        * `org` - Organization
      title: GlobalVisibilityEnum
    SimpleUser:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        full_name:
          type: string
        username:
          type: string
          description: >-
            Required. 150 characters or fewer. Letters, digits and @/./+/-/_
            only.
        is_verified:
          type: boolean
        profile_picture:
          type: string
          format: uri
          description: |-
            Convert ImageFieldFile to URL string for JSON serialization.

            Args:
                obj: The model instance being serialized (typically IAMUser)

            Returns:
                str | None: The URL of the profile picture, or None if not available
      required:
        - id
        - email
        - full_name
        - username
        - is_verified
        - profile_picture
      description: >-
        Simple user serializer with profile picture from associated
        IAMUserDetail.


        Fields:
          - id, email, full_name, username, is_verified (from IAMUser)
          - profile_picture (from first related IAMUserDetail if present)
      title: SimpleUser
    PodcastList:
      type: object
      properties:
        id:
          type: integer
        uid:
          type: string
          format: uuid
        title:
          type: string
        description:
          type:
            - string
            - 'null'
        language:
          oneOf:
            - $ref: '#/components/schemas/PodcastListLanguage'
            - type: 'null'
          description: |-
            Language for the podcast content (for future use)

            * `en` - English
            * `es` - Spanish
            * `fr` - French
            * `de` - German
            * `it` - Italian
            * `pt` - Portuguese
            * `zh` - Chinese
            * `ja` - Japanese
            * `ko` - Korean
            * `ar` - Arabic
            * `ru` - Russian
            * `hi` - Hindi
        length:
          type:
            - integer
            - 'null'
          description: Target podcast length in minutes
        knowledge_level:
          $ref: '#/components/schemas/KnowledgeLevelEnum'
          description: |-
            Target knowledge level for the podcast audience

            * `beginner` - Beginner
            * `intermediate` - Intermediate
            * `advanced` - Advanced
            * `expert` - Expert
        generation_status:
          $ref: '#/components/schemas/GenerationStatusEnum'
          description: |-
            Current status of podcast generation process

            * `not_started` - Not Started
            * `generating_script` - Generating Script
            * `script_generated` - Script Generated
            * `generating_audio` - Generating Audio
            * `completed` - Completed
            * `failed` - Failed
        visibility:
          $ref: '#/components/schemas/GlobalVisibilityEnum'
        is_draft:
          type: boolean
          description: Whether this podcast is a draft
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        logo:
          type:
            - string
            - 'null'
          format: uri
          description: Logo image for the podcast (copied from experience)
        cover_image:
          type:
            - string
            - 'null'
          format: uri
          description: Cover image for the podcast
        duration_display:
          type: string
        category_name:
          type: string
        subcategory_name:
          type: string
        owner:
          $ref: '#/components/schemas/SimpleUser'
        owner_username:
          type: string
        publications:
          type: string
        rag_document_count:
          type: string
        metrics:
          type: string
        workspace_id:
          type: integer
      required:
        - id
        - uid
        - title
        - created_at
        - updated_at
        - duration_display
        - category_name
        - subcategory_name
        - owner
        - owner_username
        - publications
        - rag_document_count
        - metrics
        - workspace_id
      description: Lightweight serializer for podcast listings.
      title: PodcastList

```

## SDK Code Examples

```python
import requests

url = "https://api.example.com/api/v1/podcasts/by-url/"

payload = {}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/api/v1/podcasts/by-url/';
const options = {method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{}'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/podcasts/by-url/"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/podcasts/by-url/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/podcasts/by-url/")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/api/v1/podcasts/by-url/', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/api/v1/podcasts/by-url/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/api/v1/podcasts/by-url/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```