openapi: 3.0.3
info:
  title: GPTIntegrations proxy api for Spotify Web API - Full Playlist and Search Management
  description: GPTIntegrations proxy for Spotify api to connect with chatgpt endpoints for searching, creating, updating, deleting, and managing playlists, including user authentication.
  version: '1.0.0'
servers:
  - url: https://gptintegrations.app/api/v1

paths:
  /search:
    get:
      operationId: searchSpotifyItems
      summary: Search for Item
      description: Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.
      tags:
        - Search
      security:
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: type
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
              enum:
                - album
                - artist
                - playlist
                - track
                - show
                - episode
                - audiobook
        - name: market
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: include_external
          in: query
          required: false
          schema:
            type: string
            enum:
              - audio
      responses:
        '200':
          description: Search results matching criteria
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /playlists/{playlist_id}/tracks:
    post:
      operationId: addTracksToPlaylist
      summary: Add Tracks to Playlist
      description: Add one or more tracks to a user’s playlist.
      tags:
        - Playlists
      security:
        - bearerAuth: []
      parameters:
        - name: playlist_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uris:
                  type: array
                  items:
                    type: string
                  description: An array of Spotify URI strings representing the tracks to add.
                position:
                  type: integer
                  description: The position to insert the tracks, a zero-based index.
      responses:
        '201':
          description: Tracks added successfully
        '401':
          description: Unauthorized - User not logged in or lacks permission
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /playlists/{playlist_id}:
    get:
      operationId: getSpotifyPlaylist
      summary: Get Playlist
      description: Get a playlist owned by a Spotify user.
      tags:
        - Playlists
      security:
        - bearerAuth: []
      parameters:
        - name: playlist_id
          in: path
          required: true
          schema:
            type: string
        - name: market
          in: query
          required: false
          schema:
            type: string
        - name: fields
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Playlist details
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

    put:
      operationId: updateSpotifyPlaylistDetails
      summary: Update Playlist Details
      description: Change a playlist’s name and public/private state. (Changing a public playlist to a private playlist is only possible for the current user.)
      tags:
        - Playlists
      security:
        - bearerAuth: []
      parameters:
        - name: playlist_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                public:
                  type: boolean
                collaborative:
                  type: boolean
                description:
                  type: string
      responses:
        '200':
          description: Playlist updated successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

    delete:
      operationId: deleteSpotifyPlaylist
      summary: Delete Playlist
      description: Delete a playlist owned by a Spotify user. Requires the playlist modify public or playlist modify private scope.
      tags:
        - Playlists
      security:
        - bearerAuth: []
      parameters:
        - name: playlist_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Playlist deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /me/playlists:
    get:
      operationId: getCurrentUserSpotifyPlaylists
      summary: Get Current User's Playlists
      description: Get a list of the playlists owned or followed by the current Spotify user.
      tags:
        - Playlists
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of user's playlists
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /users/{user_id}/playlists:
    post:
      operationId: createSpotifyUserPlaylist
      summary: Create Playlist
      description: Create a playlist for a Spotify user. The playlist will be empty until you add tracks.
      tags:
        - Playlists
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                public:
                  type: boolean
                collaborative:
                  type: boolean
      responses:
        '201':
          description: Created playlist
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /me:
    get:
      operationId: getCurrentUser
      summary: Get Current User
      description: Get details of the currently logged in user.
      tags:
        - User
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Details of the current user
          content:
            application/json:
              schema:
                type: object
                properties:
                  display_name:
                    type: string
                  email:
                    type: string
                  id:
                    type: string
                  type:
                    type: string
                    enum:
                      - user
                  uri:
                    type: string
        '401':
          description: Unauthorized - User not logged in
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests

  /me/player/pause:
    put:
      operationId: pausePlayback
      summary: Pause Playback
      description: Pauses playback on the user's active device.
      tags:
        - Player
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Playback paused successfully
        '401':
          description: Unauthorized - User not logged in or lacks permission
        '403':
          description: Forbidden
        '404':
          description: No active device found
        '429':
          description: Too Many Requests

  /me/player/next:
    post:
      operationId: skipToNextTrack
      summary: Skip To Next Track
      description: Skips to next track in the user's queue.
      tags:
        - Player
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Skipped to next track successfully
        '401':
          description: Unauthorized - User not logged in or lacks permission
        '403':
          description: Forbidden
        '404':
          description: No active device found
        '429':
          description: Too Many Requests

  /me/player/play:
    post:
      operationId: startPlaylist
      summary: Start a Specific Playlist
      description: Starts playback of a specific playlist on the user's active device.
      tags:
        - Player
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                context_uri:
                  type: string
                  description: The Spotify URI for the playlist to play.
                offset:
                  type: object
                  properties:
                    position:
                      type: integer
                      description: The index of the track in the playlist to start at.
                position_ms:
                  type: integer
                  description: Indicates from what position to start playback in milliseconds.
      responses:
        '204':
          description: Playback started successfully
        '400':
          description: Bad Request
        '401':
          description: Unauthorized - User not logged in or lacks permission
        '403':
          description: Forbidden
        '404':
          description: No active device found
        '429':
          description: Too Many Requests