openapi: 3.1.0
info:
  title: Viberate API
  version: '2026-10-12'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-12: 6 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Viberate has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 5
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-12'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://api-docs.cluster.viberate.com/public-api.json
servers:
- url: https://viberate.ams3.cdn.digitaloceanspaces.com
paths:
  /artist/advanced/search:
    get:
      operationId: get_artist_advanced_search
      tags:
      - Artist
      summary: Artist Advanced Search by Name
      description: Advanced search for artists by their name. Search is elastic, so approximates can provide correct search results.
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Artist’s name
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Maximum number of results per page
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Offset of results
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtistAdvancedSearchResponse'
      x-evidence:
        kind: documentation
  /artist/by-channel/{channelname}/{linkid}:
    get:
      operationId: get_artist_by_channel_channelname_linkid
      tags:
      - Artist
      summary: Artist Search by Channel
      description: Search for artists by their channel ID.
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      parameters:
      - name: channelname
        in: path
        required: true
        schema:
          type: string
      - name: linkid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtistByChannelChannelnameLinkidResponse'
      x-evidence:
        kind: documentation
  /artist/search:
    get:
      operationId: get_artist_search
      tags:
      - Artist
      summary: Artist Search by Name
      description: Search for artists by their name. Search is elastic, so approximates can provide correct search results.
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Artist’s name
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Maximum number of results per page
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Offset of results
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtistSearchResponse'
      x-evidence:
        kind: documentation
  /artist/viberate/chart:
    get:
      operationId: get_artist_viberate_chart
      tags:
      - Artist
      summary: Artist Chart
      description: Get the Viberate Artist Chart, ranking artists by their overall music and social media performance in ascending order. Artists
        can be filtered and sorted by available parameters.
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      parameters:
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: Sort by parameters
      - name: timeframe
        in: query
        required: false
        schema:
          type: string
        description: Sort by timeframe
      - name: genres
        in: query
        required: false
        schema:
          type: integer
        description: Filter by genres
      - name: subgenres
        in: query
        required: false
        schema:
          type: integer
        description: Filter by subgenres
      - name: spotify-genres
        in: query
        required: false
        schema:
          type: integer
        description: Filter by spotify genres
      - name: hotness
        in: query
        required: false
        schema:
          type: string
        description: Filter by the HOT tag
      - name: countries
        in: query
        required: false
        schema:
          type: string
        description: Filter by country
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: Filter by status
      - name: verified
        in: query
        required: false
        schema:
          type: boolean
        description: Filter by verified/unverified artists
      - name: uuid
        in: query
        required: false
        schema:
          type: string
        description: Filter by aritst UUID
      - name: labels
        in: query
        required: false
        schema:
          type: string
        description: Filter by major labels
      - name: exclude-countries
        in: query
        required: false
        schema:
          type: string
        description: Filter by excluding countries
      - name: first-release-date
        in: query
        required: false
        schema:
          type: string
        description: Filter by first release date
      - name: sort-by-pct
        in: query
        required: false
        schema:
          type: boolean
        description: Sort by percentage
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtistViberateChartResponse'
      x-evidence:
        kind: documentation
  /rate-limit/status:
    get:
      operationId: get_rate_limit_status
      tags:
      - Rate Limit
      summary: Rate Limit Status
      description: Get your current rate limit status.
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRateLimitStatusResponse'
      x-evidence:
        kind: documentation
  /share/docs-logo.png:
    get:
      operationId: get_share_docs_logo_png
      tags:
      - Share
      summary: GET /share/docs-logo.png
      x-source: https://api-docs.cluster.viberate.com/public-api.json
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetShareDocsLogoPngResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H 'Accept: application/json' -H 'Access-Key: {API token}' {URL} `\",\n    \"version\": \"1.24.0\",\n    \"x-logo\": {\n\
          \      \"url\": \"https://viberate.ams3.cdn.digitaloceanspaces.com/share/docs-logo.png\",\n      \"altText\": \"Viberate logo\",\n \
          \     \"href\": \"https://www.viberate.com/home\"\n    }\n  },\n  \"host\": \"data.viberate.com/api\",\n  \"basePath\": \"/v1\",\n \
          \ \"schemes\": [\"https\"],\n  \"securityDefinitions\": {\n  "
components:
  schemas:
    GetArtistAdvancedSearchResponse:
      type: object
      properties:
        api_version:
          type: string
        data:
          type: array
          description: List of artist objects with Spotify data
        data[].spotify_id:
          type: string
        data[].name:
          type: string
        data[].image:
          type: string
        data[].genres:
          type: array
        pagination:
          type: object
    GetArtistByChannelChannelnameLinkidResponse:
      type: object
      properties:
        api_version:
          type: string
        data:
          type: object
        data.uuid:
          type: string
        data.name:
          type: string
        data.slug:
          type: string
        data.image:
          type: string
        data.rank:
          type: integer
        data.status:
          type: string
        data.verified:
          type: boolean
        data.country:
          type: object
        data.city:
          type: object
        data.genre:
          type: object
        data.subgenres:
          type: array
    GetArtistSearchResponse:
      type: object
      properties:
        api_version:
          type: string
        data:
          type: array
          description: List of artist objects
        data[].uuid:
          type: string
        data[].name:
          type: string
        data[].slug:
          type: string
        data[].image:
          type: string
        data[].rank:
          type: integer
        data[].status:
          type: string
        data[].verified:
          type: boolean
        data[].country:
          type: object
        data[].city:
          type: object
        data[].genre:
          type: object
        data[].subgenres:
          type: array
        data[].spotify_genres:
          type: array
        pagination:
          type: object
    GetArtistViberateChartResponse:
      type: object
      properties:
        api_version:
          type: string
        data:
          type: array
          description: List of artist chart entries
        pagination:
          type: object
    GetRateLimitStatusResponse:
      type: object
      properties:
        api_version:
          type: string
        data:
          type: object
          description: Contains limit information
        data.limit:
          type: integer
        data.remaining:
          type: integer
        data.status:
          type: string
          description: UNDER_LIMIT or OVER_LIMIT
    GetShareDocsLogoPngResponse:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
tags:
- name: Artist
- name: Rate Limit
- name: Share