> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List playlists

> Lists playlists within a project



## OpenAPI

````yaml get /projects/{project_id}/playlists
openapi: 3.0.1
info:
  title: BeyondWords REST API
  description: |-
    This is the documentation for the BeyondWords REST API.
              You can use this API to use BeyondWords programmatically.
              You can get your API Key and Project ID for each project in the Project settings tab in the BeyondWords
              <a href="https://dash.beyondwords.io/dashboard">dashboard</a>.
  version: 1.0.0
servers:
  - url: https://api.beyondwords.io/v1
security: []
paths:
  /projects/{project_id}/playlists:
    parameters:
      - name: project_id
        in: path
        description: The numeric ID of your project
        required: true
        schema:
          type: string
    get:
      tags:
        - Playlists
      summary: List
      description: Lists playlists within a project
      operationId: playlists#index
      parameters:
        - name: filter[title]
          in: query
          required: false
          description: The partial title to filter by
          schema:
            type: string
        - name: filter[settings.title]
          in: query
          required: false
          description: The partial settings title to filter by
          schema:
            type: string
        - name: filter[enabled]
          in: query
          required: false
          schema:
            type: boolean
        - name: filter[types][]
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: The types of playlists to return
          required: false
        - name: order[by]
          in: query
          schema:
            type: string
            enum:
              - created
          required: false
          description: This is used to order playlists by created date
        - name: order[dir]
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          required: false
          description: This is used to order analytics in the ascending or descending order
        - name: pagination[limit]
          in: query
          required: false
          description: '''limit'' sets the number of results to return in each page.'
          schema:
            type: integer
        - name: pagination[offset]
          in: query
          required: false
          description: >-
            'offset' sets the first position to return from the results of the
            query. The default is 0, which starts the page at the first result.
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                example:
                  $ref: '#/components/examples/playlistsExample'
              schema:
                $ref: '#/components/schemas/playlistsModel'
          headers:
            X-BeyondWords-Filter:
              description: The filters fields applied (if any).
              schema:
                type: string
              required: false
            X-Pagination-Limit:
              description: |-
                The requested number of results to be returned for this request.
                          The actual number of results returned may be lower.
              schema:
                type: integer
              required: false
            X-Pagination-OffSet:
              description: >-
                The position of the first result in the response (before
                pagination was applied).
              schema:
                type: integer
              required: false
            X-Pagination-Total-Count:
              description: >-
                The total number of results returned for this query (before
                pagination was applied).
              schema:
                type: integer
              required: false
            X-BeyondWords-Order-By:
              description: The ordering field applied (if any).
              schema:
                type: string
              required: false
            X-BeyondWords-Order-Dir:
              description: The ordering direction applied (if any).
              schema:
                type: string
              required: false
        '401':
          description: Invalid authentication token
          content:
            application/json:
              examples:
                example:
                  $ref: '#/components/examples/unauthorizedErrorExample'
              schema:
                $ref: '#/components/schemas/errorModel'
      security:
        - apiKey: []
components:
  examples:
    playlistsExample:
      summary: Sample playlists response
      value:
        - id: 1
          title: My project playlist
          enabled: true
          type: project
          rules_version: '1.0'
          rules: []
          content_limit: 25
          content:
            - id: d7dfd636-098c-4b1b-83e5-15a3cba5a0bd
            - id: ed81a10c-83cd-4b1f-ab43-2aa1b4ffefc0
            - id: 1c0274ba-362d-4dea-8a34-5177061bf032
            - id: 7449fca4-2ecc-4bb8-9849-ae5c9f194fa6
            - id: eb0cbce7-6160-4d11-b0d2-ecb9eb92502c
          settings: null
          created: 2023-01-01 00:00:00 UTC
          updated: 2023-01-01 00:00:05 UTC
        - id: 2
          title: My manual playlist
          enabled: true
          type: manual
          rules_version: '1.0'
          rules: []
          content_limit: 25
          content:
            - id: d7dfd636-098c-4b1b-83e5-15a3cba5a0bd
            - id: ed81a10c-83cd-4b1f-ab43-2aa1b4ffefc0
            - id: 1c0274ba-362d-4dea-8a34-5177061bf032
          settings: null
          created: 2023-01-01 00:00:00 UTC
          updated: 2023-01-01 00:00:05 UTC
        - id: 3
          title: My auto playlist
          enabled: true
          type: auto
          rules_version: '1.0'
          rules:
            - operator: and
              conjunction:
                - field: author
                  operator: is
                  arg: John Smith
          content_limit: 25
          content:
            - id: 1c0274ba-362d-4dea-8a34-5177061bf032
          settings: null
          created: 2023-01-01 00:00:00 UTC
          updated: 2023-01-01 00:00:05 UTC
    unauthorizedErrorExample:
      summary: Unauthorized error
      value:
        code: 401
        message: Unauthorized
  schemas:
    playlistsModel:
      type: array
      items:
        $ref: '#/components/schemas/playlistModel'
    errorModel:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
        errors:
          type: array
          nullable: true
          items:
            type: object
            properties:
              location:
                type: string
              message:
                type: string
    playlistModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
        title:
          type: string
          description: The title of the playlist
        enabled:
          type: boolean
          description: Whether the playlist can be played in the BeyondWords player
        type:
          type: string
          enum:
            - project
            - manual
            - auto
          description: >-
            The type of playlist. The `project` type is generated automatically.
            The `manual` and `auto` can set `content` and `rules` respectively
        rules_version:
          type: string
          enum:
            - 1
          nullable: true
        rules:
          type: array
          description: The rules that will be used to find content for `auto` playlists
          items:
            type: object
            description: The rules schema
            properties:
              operator:
                type: string
                enum:
                  - and or
                description: Possible values are `and` and `or`
              conjunction:
                type: array
                description: An array of conjunctions
                items:
                  type: object
                  description: The conjunction schema
        content_limit:
          type: integer
          description: The maximum number of content items that will appear in the playlist
        content:
          type: array
          description: >-
            The content of the playlist (a reduced set of fields are returned).
            Only the `id` field is returned for the playlists index endpoint
          items:
            $ref: '#/components/schemas/contentPartialModel'
        created:
          type: string
          format: date-time
          description: Time at which the object was created (ISO 8601)
        settings:
          $ref: '#/components/schemas/feedModel'
          nullable: true
        updated:
          type: string
          format: date-time
          description: Time at which the object was updated (ISO 8601)
    contentPartialModel:
      type: object
      properties:
        id:
          type: string
          description: Unique UUID or the source_id for the object
        status:
          type: string
          enum:
            - draft
            - queued
            - processing
            - processed
            - skipped
            - error
          description: >-
            The current status of the content processing operation. This value
            will change as the content is processed.
        type:
          type: string
          enum:
            - auto_segment
            - manual_segment
            - audio_upload
          description: >-
            The content type. Possible values are `auto_segment`,
            `manual_segment` or `audio_upload`
        title:
          type: string
          description: The content title
          nullable: true
        title_enabled:
          type: boolean
          description: The flag to enable title segments in audio
        body_enabled:
          type: boolean
          description: The flag to enable body segments in audio
        summary_enabled:
          type: boolean
          description: The flag to enable summary audio
        summary_title_enabled:
          type: boolean
          description: The flag to include title text and audio segments in summaries
        source_id:
          type: string
          description: The externally-provided source identifier of the content
          nullable: true
        source_url:
          type: string
          description: The URL that contains the source content
          nullable: true
        author:
          type: string
          description: The author of the content
          nullable: true
        image_url:
          type: string
          description: The feature image URL of the content
          nullable: true
          deprecated: true
        metadata:
          type: object
          description: The arbitrary metadata associated with content
          nullable: true
        audio:
          type: array
          description: The array of audio files for the entire content
          items:
            $ref: '#/components/schemas/contentAudioModel'
        video:
          type: array
          description: The array of video files for the entire content
          items:
            $ref: '#/components/schemas/contentVideoModel'
        audio_with_intro_outro:
          type: array
          items:
            $ref: '#/components/schemas/contentAudioModel'
        summarization:
          type: object
          properties:
            audio:
              type: array
              description: The array of summary audio files for the entire content
              items:
                $ref: '#/components/schemas/contentAudioModel'
            video:
              type: array
              description: The array of summary video files for the entire content
              items:
                $ref: '#/components/schemas/contentVideoModel'
        published:
          type: boolean
          description: >-
            Whether the content will appear in the BeyondWords players and
            podcast feeds
        video_published:
          type: boolean
          description: >-
            Whether the content will appear in the BeyondWords video players and
            podcast video feeds
        publish_date:
          type: string
          description: >-
            Time at which the content was published or is scheduled to be
            published (ISO 8601)
          nullable: true
        ads_enabled:
          type: boolean
          description: >-
            Whether adverts will play for this content in the BeyondWords
            players
        auto_segment_updates_enabled:
          type: boolean
          description: >-
            Whether the media files will be regenerated when the text content is
            updated with `auto_segment`
        background_track:
          type: object
          nullable: true
          properties:
            enabled:
              type: boolean
              nullable: false
            track:
              type: object
              nullable: true
              properties:
                id:
                  type: integer
                name:
                  type: string
                custom:
                  type: boolean
                volume:
                  type: integer
                url:
                  type: string
        feature_image:
          type: object
          nullable: true
          properties:
            url:
              type: string
            video_settings:
              type: object
              properties:
                enabled:
                  type: boolean
                crop_coordinates:
                  type: object
                  properties:
                    '16:9':
                      type: array
                      items:
                        type: number
                      maxItems: 4
                    '9:16':
                      type: array
                      items:
                        type: number
                      maxItems: 4
        feature_video:
          type: object
          nullable: true
          properties:
            url:
              type: string
            video_settings:
              type: object
              properties:
                enabled:
                  type: boolean
                volume:
                  type: integer
                crop_coordinates:
                  type: object
                  properties:
                    '16:9':
                      type: array
                      items:
                        type: number
                      maxItems: 4
                    '9:16':
                      type: array
                      items:
                        type: number
                      maxItems: 4
        summarization_settings:
          allOf:
            - $ref: '#/components/schemas/summarizationSettingsModel'
          nullable: true
        language:
          type: string
          description: The default language of the content
          nullable: true
        created:
          type: string
          format: date-time
          description: Time at which the object was created (ISO 8601)
        updated:
          type: string
          format: date-time
          description: Time at which the object was updated (ISO 8601)
    feedModel:
      type: object
      properties:
        title:
          type: string
          description: The title of the podcast feed
        enabled:
          type: boolean
          description: Whether or not the podcast feed URL is available
        description:
          type: string
          description: The description of the podcast feed
          nullable: true
        homepage_url:
          type: string
          description: The homepage URL of the podcast feed
          nullable: true
        image_url:
          type: string
          description: The image URL of the podcast feed
          nullable: true
        apple_categories:
          type: object
          description: Category data for Apple Podcasts and Spotify
          properties:
            primary_category:
              type: string
              description: The primary category of the podcast
              nullable: true
            primary_subcategory:
              type: string
              description: The primary subcategory of the podcast
              nullable: true
            secondary_category:
              type: string
              description: The secondary category of the podcast
              nullable: true
            secondary_subcategory:
              type: string
              description: The secondary subcategory of the podcast
              nullable: true
        google_categories:
          type: array
          description: An array of Google Podcast categories of the podcast
          items:
            type: string
        language:
          type: string
          description: The podcast feed language
          nullable: true
        owner_name:
          type: string
          description: The name of the administrator for the podcast
          nullable: true
        owner_email:
          type: string
          description: The email of the administrator for the podcast
          nullable: true
        author_names:
          type: array
          description: The names of writers/speakers who contribute to the podcast
          items:
            type: string
        explicit_enabled:
          type: boolean
          description: Whether or not the podcast contains explicit content
        keywords:
          type: array
          description: An array of keywords to associate with the podcast
          items:
            type: string
        feed_limit:
          type: integer
          description: The maximum number of podcasts that will appear in the feed
        copyright:
          type: string
          description: The copyright tag of the podcast feed
          nullable: true
    contentAudioModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
        variant:
          type: string
          enum:
            - article
            - summary
          description: The variant type of the audio content
        video_size:
          type: object
          nullable: true
          properties:
            name:
              type: string
            description:
              type: string
              nullable: true
            width:
              type: integer
            height:
              type: integer
        content_type:
          type: string
          enum:
            - audio/mpeg
            - application/x-mpegURL
          description: MIME type of the audio file (MP3 or HLS playlist)
          nullable: true
        url:
          type: string
          description: Direct URL to the audio file
          nullable: true
          format: uri
        duration:
          type: integer
          description: Duration of the audio file in milliseconds
          nullable: true
        base64_file:
          type: string
          description: Base64-encoded content of HLS playlist metadata files
          nullable: true
    contentVideoModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
        variant:
          type: string
          enum:
            - article
            - summary
          description: The variant type of the video content
        video_size:
          type: object
          nullable: true
          properties:
            name:
              type: string
            description:
              type: string
              nullable: true
            width:
              type: integer
            height:
              type: integer
        content_type:
          type: string
          enum:
            - video/mp4
            - application/x-mpegURL
          description: MIME type of the video file (MP4 or HLS playlist)
          nullable: true
        url:
          type: string
          description: Direct URL to the video file
          nullable: true
        duration:
          type: integer
          description: Duration of the video file in milliseconds
          nullable: true
        base64_file:
          type: string
          description: >-
            The content of the media file encoded as base64. Only present for
            .m3u8 metadata files
          nullable: true
    summarizationSettingsModel:
      type: object
      properties:
        enabled:
          type: boolean
          nullable: false
          description: When true, AI-powered summarization is enabled
        prompt:
          type: string
          nullable: true
          description: Custom prompt for AI summarization generation
        model:
          type: string
          enum:
            - gpt-5-nano
            - gpt-5-mini
            - gpt-5
            - gpt-5.1
          nullable: true
        temperature:
          type: number
          nullable: true
          description: >-
            Controls randomness in AI summarization (0.0 = deterministic, 2.0 =
            very random)
          minimum: 0
          maximum: 2
        limit_token_usage:
          type: integer
          nullable: true
          description: Maximum number of tokens to use for AI summarization
          minimum: 1
          maximum: 3000
        template:
          $ref: '#/components/schemas/summarizationSettingsTemplatesModel'
          nullable: true
    summarizationSettingsTemplatesModel:
      type: array
      items:
        $ref: '#/components/schemas/summarizationSettingsTemplateModel'
    summarizationSettingsTemplateModel:
      type: object
      properties:
        id:
          type: integer
        slug:
          type: string
          description: Unique identifier for the object
        name:
          type: string
          nullable: false
        model:
          type: string
          enum:
            - gpt-5-nano
            - gpt-5-mini
            - gpt-5
            - gpt-5.1
          nullable: true
        prompt:
          type: string
          nullable: true
          description: Custom prompt for AI summarization generation
          maxLength: 3000
        temperature:
          type: number
          nullable: true
          description: >-
            Controls randomness in AI summarization (0.0 = deterministic, 2.0 =
            very random)
          minimum: 0
          maximum: 2
        limit_token_usage:
          type: integer
          nullable: true
          description: Maximum number of tokens to use for AI summarization
          minimum: 1
          maximum: 500
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-Api-Key
      in: header

````