Genius

opencollection: 1.0.0
info:
  name: Genius API
  version: 1.0.0
items:
- info:
    name: Account
    type: folder
  items:
  - info:
      name: Get Current Account
      type: http
    http:
      method: GET
      url: https://api.genius.com/account
      params:
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns details about the authenticated user. Requires the `me` scope.
- info:
    name: Search
    type: folder
  items:
  - info:
      name: Search Genius
      type: http
    http:
      method: GET
      url: https://api.genius.com/search
      params:
      - name: q
        value: ''
        type: query
        description: The search query.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 5 for search).
      - name: page
        value: ''
        type: query
        description: Page of results to return (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: 'Search across songs, artists, and lyrics. Returns hit objects keyed by

      type, currently only `song` results are surfaced by the public API.

      '
- info:
    name: Songs
    type: folder
  items:
  - info:
      name: Get Song
      type: http
    http:
      method: GET
      url: https://api.genius.com/songs/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric song ID.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns full song metadata including artist, album, release date, media, and song relationships.
  - info:
      name: Get Song Comments
      type: http
    http:
      method: GET
      url: https://api.genius.com/songs/:id/comments
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric song ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Lists comments left on a song page.
  - info:
      name: Get Song Activity
      type: http
    http:
      method: GET
      url: https://api.genius.com/songs/:id/activity
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric song ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Activity stream for a song (annotations created, comments posted, edits, etc.).
  - info:
      name: Get Song Contributors
      type: http
    http:
      method: GET
      url: https://api.genius.com/songs/:id/contributors
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric song ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: List of users who have contributed to the song (transcribers, annotators, editors).
- info:
    name: Artists
    type: folder
  items:
  - info:
      name: Get Artist
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns artist metadata including bio, follower count, social handles, and verification status.
  - info:
      name: List Artist Songs
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id/songs
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: sort
        value: ''
        type: query
        description: Sort key for the result set.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns a paginated list of songs for the artist, sortable by title, popularity, or release date.
  - info:
      name: List Artist Albums
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id/albums
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns albums associated with the artist.
  - info:
      name: Get Artist Activity
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id/activity
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Activity stream covering all of the artist's songs.
  - info:
      name: List Artist Followers
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id/followers
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns users who follow the artist.
  - info:
      name: Get Artist Leaderboard
      type: http
    http:
      method: GET
      url: https://api.genius.com/artists/:id/leaderboard
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric artist ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns the top "scholars" — users with the highest contribution score for this artist.
- info:
    name: Albums
    type: folder
  items:
  - info:
      name: Get Album
      type: http
    http:
      method: GET
      url: https://api.genius.com/albums/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric album ID.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns album metadata including title, artist, release date, and cover art.
  - info:
      name: List Album Tracks
      type: http
    http:
      method: GET
      url: https://api.genius.com/albums/:id/tracks
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric album ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns the album's tracklist in order.
  - info:
      name: Get Album Comments
      type: http
    http:
      method: GET
      url: https://api.genius.com/albums/:id/comments
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric album ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Comments left on the album page.
  - info:
      name: Get Album Cover Arts
      type: http
    http:
      method: GET
      url: https://api.genius.com/albums/:id/cover_arts
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric album ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns all cover-art images attached to the album.
  - info:
      name: Get Album Leaderboard
      type: http
    http:
      method: GET
      url: https://api.genius.com/albums/:id/leaderboard
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric album ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Top contributors to the album.
- info:
    name: Annotations
    type: folder
  items:
  - info:
      name: Get Annotation
      type: http
    http:
      method: GET
      url: https://api.genius.com/annotations/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns the full content of an annotation along with its referent.
  - info:
      name: Delete Annotation
      type: http
    http:
      method: DELETE
      url: https://api.genius.com/annotations/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Deletes an annotation owned by the authenticated user. Requires the `manage_annotation` scope.
  - info:
      name: Create Annotation
      type: http
    http:
      method: POST
      url: https://api.genius.com/annotations
      body:
        type: json
        data: '{}'
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Creates a new annotation attached to a referent (or a fragment of a web page). Requires the `create_annotation`
      scope.
  - info:
      name: Get Annotation Edits
      type: http
    http:
      method: GET
      url: https://api.genius.com/annotations/:id/edits
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns the version history of an annotation.
  - info:
      name: Get Annotation Comments
      type: http
    http:
      method: GET
      url: https://api.genius.com/annotations/:id/comments
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns comments left on an annotation.
  - info:
      name: Upvote Annotation
      type: http
    http:
      method: PUT
      url: https://api.genius.com/annotations/:id/vote
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Upvotes an annotation as the authenticated user. Requires the `vote` scope.
  - info:
      name: Remove Annotation Vote
      type: http
    http:
      method: DELETE
      url: https://api.genius.com/annotations/:id/vote
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Removes the authenticated user's vote from the annotation. Requires the `vote` scope.
  - info:
      name: Downvote Annotation
      type: http
    http:
      method: PUT
      url: https://api.genius.com/annotations/:id/downvote
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric annotation ID.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Downvotes an annotation as the authenticated user. Requires the `vote` scope.
- info:
    name: Referents
    type: folder
  items:
  - info:
      name: List Referents
      type: http
    http:
      method: GET
      url: https://api.genius.com/referents
      params:
      - name: song_id
        value: ''
        type: query
        description: Filter by song.
      - name: web_page_id
        value: ''
        type: query
        description: Filter by web page.
      - name: created_by_id
        value: ''
        type: query
        description: Filter by referent creator.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: 'Returns referents (lyric fragments) filtered by `song_id`, `web_page_id`,

      or `created_by_id`. Exactly one of these parameters must be supplied.

      '
  - info:
      name: Get Referents By IDs
      type: http
    http:
      method: GET
      url: https://api.genius.com/referents/:ids
      params:
      - name: ids
        value: ''
        type: path
        description: Comma-separated referent IDs.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns one or more referents by their IDs (comma-separated).
- info:
    name: Web Pages
    type: folder
  items:
  - info:
      name: Lookup Web Page
      type: http
    http:
      method: GET
      url: https://api.genius.com/web_pages/lookup
      params:
      - name: raw_annotatable_url
        value: ''
        type: query
        description: Untransformed URL of the page.
      - name: canonical_url
        value: ''
        type: query
        description: Canonical URL declared by the page.
      - name: og_url
        value: ''
        type: query
        description: Open Graph URL declared by the page.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: 'Looks up a web page record (the surface on which Genius annotations live)

      by one of `raw_annotatable_url`, `canonical_url`, or `og_url`.

      '
- info:
    name: Users
    type: folder
  items:
  - info:
      name: Get User
      type: http
    http:
      method: GET
      url: https://api.genius.com/users/:id
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric user ID.
      - name: text_format
        value: ''
        type: query
        description: Format for textual fields in the response.
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns user profile data.
  - info:
      name: Get User Contributions
      type: http
    http:
      method: GET
      url: https://api.genius.com/users/:id/contributions
      params:
      - name: id
        value: ''
        type: path
        description: Genius numeric user ID.
      - name: type
        value: ''
        type: query
        description: Restrict to a specific contribution type.
      - name: per_page
        value: ''
        type: query
        description: Number of results per page (max 50).
      - name: page
        value: ''
        type: query
        description: Page index (1-indexed).
      auth:
        type: oauth2
        flow: authorization_code
        authorizationUrl: https://api.genius.com/oauth/authorize
        accessTokenUrl: https://api.genius.com/oauth/token
        credentials:
          clientId: '{{clientId}}'
          clientSecret: '{{clientSecret}}'
    docs: Returns contributions made by the user (annotations, songs, transcriptions, suggestions, etc.).
bundled: true