# List Podcasts by Publication URL

GET /api/v1/podcasts/by-url/

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/:
    get:
      operationId: by-url-list
      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
      parameters:
        - name: category
          in: query
          required: false
          schema:
            type: string
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: description
          in: query
          required: false
          schema:
            type: string
        - name: focus_area
          in: query
          required: false
          schema:
            type: string
        - name: generation_status
          in: query
          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
          required: false
          schema:
            $ref: >-
              #/components/schemas/ApiV1PodcastsByUrlGetParametersGenerationStatus
        - name: is_draft
          in: query
          required: false
          schema:
            type: boolean
        - name: knowledge_level
          in: query
          description: |-
            Target knowledge level for the podcast audience

            * `beginner` - Beginner
            * `intermediate` - Intermediate
            * `advanced` - Advanced
            * `expert` - Expert
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1PodcastsByUrlGetParametersKnowledgeLevel'
        - name: max_length
          in: query
          required: false
          schema:
            type: integer
        - name: min_length
          in: query
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: publication
          in: query
          required: false
          schema:
            type: string
        - name: subcategory
          in: query
          required: false
          schema:
            type: string
        - name: tags
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          required: false
          schema:
            type: string
        - name: visibility
          in: query
          required: false
          schema:
            type: string
        - name: voice_type
          in: query
          required: false
          schema:
            type: string
      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/PaginatedPodcastListList'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
components:
  schemas:
    ApiV1PodcastsByUrlGetParametersGenerationStatus:
      type: string
      enum:
        - completed
        - failed
        - generating_audio
        - generating_script
        - not_started
        - script_generated
      title: ApiV1PodcastsByUrlGetParametersGenerationStatus
    ApiV1PodcastsByUrlGetParametersKnowledgeLevel:
      type: string
      enum:
        - advanced
        - beginner
        - expert
        - intermediate
      title: ApiV1PodcastsByUrlGetParametersKnowledgeLevel
    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
    PaginatedPodcastListList:
      type: object
      properties:
        count:
          type: integer
        next:
          type:
            - string
            - 'null'
          format: uri
        previous:
          type:
            - string
            - 'null'
          format: uri
        results:
          type: array
          items:
            $ref: '#/components/schemas/PodcastList'
      required:
        - count
        - results
      title: PaginatedPodcastListList

```

## SDK Code Examples

```python
import requests

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

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

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

print(response.json())
```

```javascript
const url = 'https://api.example.com/api/v1/podcasts/by-url/';
const options = {method: 'GET', 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("GET", 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::Get.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.get("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('GET', '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.GET);
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 = "GET"
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()
```