openapi: 3.0.0
info:
  version: 1.0.0
  title: Reference
  description: |
    [PraiseCharts](https://www.praisecharts.com) API public endpoints
  contact:
    name: PraiseCharts
    email: developers@praisecharts.com
    url: https://praisecharts.com/
  termsOfService: https://www.praisecharts.com/company/praisecharts-api-usage-agreement/
paths:
  /oauth/request_token:
    servers:
      - url: https://www.praisecharts.com/api
    post:
      summary: Request Token
      tags:
        - OAuth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  oauth_token:
                    type: string
                    minLength: 1
                  oauth_token_secret:
                    type: string
                    minLength: 1
                  oauth_callback_confirmed:
                    type: boolean
                required:
                  - oauth_token
                  - oauth_token_secret
                  - oauth_callback_confirmed
              examples:
                Example Response:
                  value:
                    oauth_token: ab079985927a23793f41170194c1b3
                    oauth_token_secret: 747ce9c680
                    oauth_callback_confirmed: true
          headers: {}
        '500':
          description: Internal Server Error
      description: >-
        Allows a Consumer application to obtain an OAuth Request Token to
        request user authorization. 


        This method fulfills Section 6.1 of the OAuth 1.0 authentication flow.


        This request MUST be signed and include the following in the
        Authorization header


        ```bash

        OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog", 

        oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",

        oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D",

        oauth_signature_method="HMAC-SHA1",

        oauth_timestamp="1318622958",

        oauth_version="1.0"

        ``` 



        [See how to create a
        signature](https://developer.praisecharts.com/guides/authorization/key-concepts)
      parameters:
        - schema:
            type: string
            example: >-
              OAuth oauth_nonce="K7ny27JTpKVsTgdyLdDfmQQWVLERj2zAK5BslRsqyw",
              oauth_callback="http%3A%2F%2Fmyapp.com%3A3005%2Ftwitter%2Fprocess_callback",
              oauth_signature_method="HMAC-SHA1", oauth_timestamp="1300228849",
              oauth_consumer_key="OqEqJeafRSF11jBMStrZz",
              oauth_signature="Pc%2BMLdv028fxCErFyi8KXFM%2BddU%3D",
              oauth_version="1.0"`
          in: header
          name: Authorization
          required: true
          description: Signed OAuth string
  /oauth/authorize:
    get:
      servers:
        - url: https://www.praisecharts.com/api
      summary: Authorize
      responses:
        '200':
          description: OK
      description: >-
        Allows a Consumer application to use an OAuth Request Token to request
        user authorization. This method fulfills Section 6.2 of the OAuth 1.0
        authentication flow.
      parameters:
        - schema:
            type: string
            example: 3756b0ec8c0e232123623f761b5017
          in: query
          name: oauth_token
          required: true
          description: unauthorized oauth_token generated from /oauth/request_token
      security: []
      tags:
        - OAuth
  /oauth/access_token:
    post:
      servers:
        - url: https://www.praisecharts.com/api
      summary: Access token
      tags:
        - OAuth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: string
                properties:
                  oauth_token:
                    type: string
                  oauth_token_secret:
                    type: string
                  library_id:
                    type: string
      parameters:
        - schema:
            type: string
            example: >-
              OAuth oauth_consumer_key="acg",
              oauth_nonce="c1f9a3b8e83e0fe7d12ff201b0f68089",
              oauth_signature="jquFmwtxfTM49wddcuAsxjjYa%2fI%3d",
              oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318622958",
              oauth_token="3756b0ec8c0e232123623f761b5017",
              oauth_verifier="aa4bf7d3250f45a4eb4549be9fbde8",
              oauth_version="1.0"
          in: header
          name: Authorization
          required: true
      description: >-
        Allows a Consumer application to exchange the OAuth Request Token for an
        OAuth Access Token. 


        This method fulfills Section 6.3 of the OAuth 1.0 authentication flow.


        This request MUST be signed per [Signing
        Requests](/guides/authorization/creating-a-signature) and include the
        following:

        ```bash

        OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog", 

        oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",

        oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D",

        oauth_signature_method="HMAC-SHA1",

        oauth_timestamp="1318622958",

        oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb",

        oauth_verifier="aa4bf7d3250f45a4eb4549be9fbde8",

        oauth_version="1.0"

        ``` 



        [See how to create a
        signature](https://pcapidocs.netlify.app/guides/authorization/key-concepts)
  /library/search:
    get:
      summary: Search Library
      description: '[Search Guide](/guides/catalog/search)'
      tags:
        - Library
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  in_library:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                      total:
                        type: number
                      limit:
                        type: number
                      from:
                        type: number
                  other_results:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                      total:
                        type: number
                      limit:
                        type: number
                      from:
                        type: number
        '500':
          description: Invalid OAuth Signature
      parameters:
        - schema:
            type: string
          in: query
          name: q
          required: false
          description: |-
            Your search query. 

             For accurate results search {song title} {artist name} 

             The query field searches against title, author names, artist names, album name, themes PCID, CCLI, Product name, and more.
        - schema:
            type: array
            items:
              type: string
              enum:
                - sheet_music
                - audio_tracks
                - patches
          in: query
          name: product_types[]
          required: false
          description: >-
            Will only return products of the specified type. 


            If a song matches the query but doesn't have the specified type.
            items[x].products will be empty. 


            Allowed values: 'sheet_music'  'audio_tracks'  'patches' 

             Defaults to all.
        - schema:
            type: number
          in: query
          name: ccli_number
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: themes[]
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: keys[]
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_codes[]
          required: false
        - schema:
            type: boolean
          in: query
          name: search_lyrics
          required: false
          description: >-
            If true, will apply search term against lyrics as well as other
            fields. 


            Defaults to false.
        - schema:
            type: string
          in: query
          name: exists
          required: false
          description: >-
            Specify a property that must contain a truthy value for the product
            to be returned. 


            For example, if you want to return only products that have a Tempo,
            you would use exists=details.tempo. 


            If the product doesn't have the specified property, it will be
            excluded from the results.
        - schema:
            type: array
            items:
              type: string
          in: query
          name: arr_includes[]
          required: false
          description: >-
            pass in an array of strings that represent what parts of the model
            you want back. 


            Example: 


            arr_includes[]='id' 


            arr_includes[]=“details.title' 


            arr_includes[]='details.artists.names' 


            arr_includes[]=“details.album.images.md.url' 

             Would only return those fields in the response.
        - schema:
            type: number
          in: query
          name: limit
          required: false
          description: |-
            The maximum number of results to return in each item type.

             Default value:
            10

            Example value:
                        20
        - schema:
            type: number
          in: query
          name: from
          required: false
          description: >-
            The index of the first result to return. Use with limit for
            pagination.
        - schema:
            type: string
          in: header
          name: Authorization
          required: true
  /library/import-arrangement/{catalog_item_id}:
    get:
      summary: Import Arrangement
      description: >-
        Get an array of simple objects representing all of the files the user
        has access to organized by key 


        [Figma
        Example](https://www.figma.com/file/H6Dup68l63b32q2m0zPH0R/Import-Experience?node-id=2%3A76)
      tags:
        - Library
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  G:
                    type: array
                    items:
                      type: object
                      properties:
                        product_type:
                          type: string
                          enum:
                            - sheet_music
                            - audio_tracks
                            - patches
                        file_type:
                          type: string
                          example: pdf
                          enum:
                            - pdf
                            - zip
                            - mp3
                            - wav
                        name:
                          type: string
                          example: Chord Chart
                        download:
                          type: string
                          example: >-
                            https://api.praisecharts.com/v1.0/download?skus[]=73318-W&keys[]=G
        '500':
          description: Invalid OAuth Signature
      parameters:
        - schema:
            type: string
          in: path
          name: catalog_item_id
          required: true
          example: '73318'
          description: Catalog Item ID
        - schema:
            type: array
            items:
              type: string
              example: G
          in: query
          name: keys[]
          required: false
          description: Keys
  /catalog/search:
    get:
      summary: Search Catalog
      description: '[Search Guide](/guides/catalog/search)'
      tags:
        - Catalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  arrangements:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                      total:
                        type: number
                      limit:
                        type: number
                      from:
                        type: number
        '500':
          description: Invalid OAuth Signature
      parameters:
        - schema:
            type: string
          in: query
          name: q
          required: false
          description: |-
            Your search query. 

             For accurate results search {song title} {artist name} 

             The query field searches against title, author names, artist names, album name, themes PCID, CCLI, Product name, and more.
        - schema:
            type: array
            items:
              type: string
              enum:
                - sheet_music
                - audio_tracks
                - patches
          in: query
          name: product_types[]
          required: false
          description: >-
            Will only return products of the specified type. 


            If a song matches the query but doesn't have the specified type.
            items[x].products will be empty. 


            Allowed values: 'sheet_music'  'audio_tracks'  'patches' 

             Defaults to all.
        - schema:
            type: number
          in: query
          name: ccli_number
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: themes[]
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: keys[]
          required: false
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_codes[]
          required: false
        - schema:
            type: boolean
          in: query
          name: search_lyrics
          required: false
          description: >-
            If true, will apply search term against lyrics as well as other
            fields. 


            Defaults to false.
        - schema:
            type: string
          in: query
          name: exists
          required: false
          description: >-
            Specify a property that must contain a truthy value for the product
            to be returned. 


            For example, if you want to return only products that have a Tempo,
            you would use exists=details.tempo. 


            If the product doesn't have the specified property, it will be
            excluded from the results.
        - schema:
            type: array
            items:
              type: string
          in: query
          name: arr_includes[]
          required: false
          description: >-
            pass in an array of strings that represent what parts of the model
            you want back. 


            Example: 


            arr_includes[]='id' 


            arr_includes[]=“details.title' 


            arr_includes[]='details.artists.names' 


            arr_includes[]=“details.album.images.md.url' 

             Would only return those fields in the response.
        - schema:
            type: number
          in: query
          name: limit
          required: false
          description: |-
            The maximum number of results to return in each item type.

             Default value:
            10

            Example value:
                        20
        - schema:
            type: number
          in: query
          name: from
          required: false
          description: >-
            The index of the first result to return. Use with limit for
            pagination.
        - schema:
            type: string
          in: header
          name: Authorization
          required: true
  /download:
    get:
      servers:
        - url: https://api.praisecharts.com/v1.0
      summary: Download
      tags:
        - Download
      responses:
        '200':
          description: PDF or Zip file
        '404':
          description: You do not own this product.
        '500':
          description: Invalid OAuth Signature
      description: >-
        The download route uses a different Base URL
        https://api.praisecharts.com/


        Array paramaters need to be passed in using PHP array syntaxt. ie:
        ***?key[]=value&?key[]=value***
         
         [Download Guide](/guides/download/bdownload-in-depth)
      parameters:
        - schema:
            type: array
            items:
              type: string
          in: query
          name: skus
          required: true
          description: ''
        - schema:
            type: array
            items:
              type: string
          in: query
          name: keys
          required: false
          description: Key Names
        - schema:
            type: array
            items:
              type: string
          in: query
          name: key_ids
          required: false
          description: Key Ids
        - schema:
            type: string
            example: cc_1col_pdf
          in: query
          name: chordpro_option
          required: false
          description: 'default: cc_2col_pdf default'
  /me:
    get:
      summary: Account
      description: Returns an object of the current user's account information
      tags:
        - User
      responses:
        '200':
          description: User Object
        '500':
          description: Invalid OAuth Signature
      parameters:
        - schema:
            type: string
            example: >-
              OAuth oauth_nonce="K7ny27JTpKVsTgdyLdDfmQQWVLERj2zAK5BslRsqyw",
              oauth_callback="http%3A%2F%2Fmyapp.com%3A3005%2Ftwitter%2Fprocess_callback",
              oauth_signature_method="HMAC-SHA1", oauth_timestamp="1300228849",
              oauth_consumer_key="OqEqJeafRSF11jBMStrZz",
              oauth_signature="Pc%2BMLdv028fxCErFyi8KXFM%2BddU%3D",
              oauth_version="1.0"`
          in: header
          name: Authorization
          required: true
          description: Signed OAuth string
servers:
  - url: https://www.praisecharts.com/api/v1.0
    description: Prod
components:
  securitySchemes:
    Authorization:
      type: http
      scheme: oauth
      description: OAuth 1.0a
  schemas: {}
tags:
  - name: OAuth
  - name: Catalog
  - name: Library
  - name: Download
  - name: User
security:
  - Authorization: []
