openapi: 3.0.1
info:
  title: Audius challenges developer_apps API
  description: '## Overview


    The Audius API provides REST access to the world''s largest open music catalog, built on the [Open Audio Protocol](https://openaudio.org). Use it to query and stream tracks, users, playlists, and more—perfect for building music players, discovery apps, and audio-native products.


    ## Key Capabilities


    - **Users** — Profiles, followers, following, search

    - **Tracks** — Search, trending, stream, favorites, reposts

    - **Playlists** — Create, update, browse, curate

    - **Resolve** — Look up content by Audius canonical URLs (e.g. `audius.co/artist/...`)

    - **Explore** — Trending content, charts, discovery

    - **Comments, Tips, Rewards** — Social features and engagement


    ## Authentication


    - **Read-only** — Most endpoints work without credentials. Use an API key for higher rate limits.

    - **Writes** — Upload, favorite, repost, and other mutations require an API key and secret. Get keys at [api.audius.co/plans](https://api.audius.co/plans) or [audius.co/settings](https://audius.co/settings).


    ## Resources


    - [API Docs](https://docs.audius.co/api) — Full reference and guides

    - [API Plans](https://api.audius.co/plans) — Get API keys (free tier available)

    - [Log in with Audius](https://docs.audius.co/developers/guides/log-in-with-audius) — OAuth for user actions

    - [JavaScript SDK](https://www.npmjs.com/package/@audius/sdk) — `@audius/sdk` for Node and browser

    '
  version: '1.0'
  contact:
    name: Audius
    url: https://audius.co
  x-logo:
    url: https://audius.co/favicons/favicon.ico
servers:
- url: https://api.audius.co/v1
  description: Production
tags:
- name: developer_apps
  description: Developer app related operations
paths:
  /developer-apps:
    post:
      tags:
      - developer_apps
      description: Create a new developer app. Indexer validates grants.
      operationId: Create Developer App
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user creating the developer app
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_developer_app_request_body'
      responses:
        '200':
          description: Developer app created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_developer_app_response'
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '500':
          description: Server error
          content: {}
  /developer-apps/{address}:
    get:
      tags:
      - developer_apps
      description: Gets developer app matching given address (API key)
      operationId: Get Developer App
      parameters:
      - name: address
        in: path
        description: A developer app address (API Key)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer_app_response'
        '400':
          description: Bad request
          content: {}
        '404':
          description: Not found
          content: {}
        '500':
          description: Server error
          content: {}
    delete:
      tags:
      - developer_apps
      description: Deletes a developer app. Indexer validates grants.
      operationId: Delete Developer App
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user who owns the developer app
        required: true
        schema:
          type: string
      - name: address
        in: path
        description: Developer app address (API Key)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Developer app deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Not found
          content: {}
        '500':
          description: Server error
          content: {}
    put:
      tags:
      - developer_apps
      description: Updates a developer app. Indexer validates grants.
      operationId: Update Developer App
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user who owns the developer app
        required: true
        schema:
          type: string
      - name: address
        in: path
        description: Developer app address (API Key)
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_developer_app_request_body'
      responses:
        '200':
          description: Developer app updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Developer app not found
          content: {}
        '500':
          description: Server error
          content: {}
  /developer-apps/{address}/register-api-key:
    post:
      tags:
      - developer_apps
      description: Register api_key and api_secret in api_keys table for developer apps created via entity manager transactions. Use when the client sends raw ManageEntity tx instead of POST /developer-apps. Inserts with rps=10, rpm=500000. Requires the app to exist in developer_apps and belong to the authenticated user.
      operationId: Register Developer App API Key
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user who owns the developer app
        required: true
        schema:
          type: string
      - name: address
        in: path
        description: Developer app address (API key)
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/register_api_key_request_body'
      responses:
        '200':
          description: API key registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/register_api_key_response'
        '400':
          description: Bad request (api_secret required)
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Developer app not found
          content: {}
        '500':
          description: Server error
          content: {}
  /developer-apps/{address}/access-keys/deactivate:
    post:
      tags:
      - developer_apps
      description: Deactivate a bearer token (API access key) for a developer app. Indexer validates grants.
      operationId: Deactivate Developer App Access Key
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user who owns the developer app
        required: true
        schema:
          type: string
      - name: address
        in: path
        description: Developer app address (API Key)
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deactivate_access_key_request_body'
      responses:
        '200':
          description: Access key deactivated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deactivate_access_key_response'
        '400':
          description: Bad request (api_access_key required)
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Developer app or access key not found
          content: {}
        '500':
          description: Server error
          content: {}
  /developer-apps/{address}/access-keys:
    post:
      tags:
      - developer_apps
      description: Create a new bearer token (API access key) for a developer app. Indexer validates grants.
      operationId: Create Developer App Access Key
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user who owns the developer app
        required: true
        schema:
          type: string
      - name: address
        in: path
        description: Developer app address (API Key)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Access key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_access_key_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Developer app not found
          content: {}
        '500':
          description: Server error
          content: {}
  /users/{id}/developer-apps:
    get:
      tags:
      - developer_apps
      description: Get developer apps for the user.
      operationId: Get Developer Apps
      parameters:
      - name: id
        in: path
        description: The user ID whose developer apps to list
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: Include metrics when set to "metrics"
        schema:
          type: string
          enum:
          - metrics
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer_apps_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
components:
  schemas:
    create_access_key_response:
      type: object
      required:
      - api_access_key
      properties:
        api_access_key:
          type: string
          description: The newly created bearer token (API access key)
    write_response:
      type: object
      properties:
        transaction_hash:
          type: string
          description: The blockchain transaction hash
        block_hash:
          type: string
          description: The blockchain block hash
        block_number:
          type: integer
          format: int64
          description: The blockchain block number/height
    deactivate_access_key_request_body:
      type: object
      required:
      - api_access_key
      properties:
        api_access_key:
          type: string
          description: The bearer token (API access key) to deactivate
    create_developer_app_request_body:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Developer app name
          example: My API Key
        description:
          type: string
          description: App description
        image_url:
          type: string
          description: App logo/image URL
        redirect_uris:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 2000
          description: Pre-registered OAuth redirect/callback URIs
    deactivate_access_key_response:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the deactivation was successful
    developer_apps_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/developer_app'
    create_developer_app_response:
      type: object
      properties:
        api_key:
          type: string
          description: The API key (address) for the developer app
        api_secret:
          type: string
          description: The private key for the developer app (for signing)
        bearer_token:
          type: string
          description: The bearer token for API authentication (use in Authorization header)
        transaction_hash:
          type: string
          description: Transaction hash of the creation
        block_hash:
          type: string
          description: The blockchain block hash
        block_number:
          type: integer
          format: int64
          description: The blockchain block number/height
    update_developer_app_request_body:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Developer app name
        description:
          type: string
          description: App description
        image_url:
          type: string
          description: App logo/image URL
        redirect_uris:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 2000
          description: Pre-registered OAuth redirect/callback URIs
    register_api_key_response:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the registration was successful
    developer_app_response:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/developer_app'
    developer_app:
      required:
      - address
      - name
      - user_id
      type: object
      properties:
        address:
          type: string
        user_id:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        redirect_uris:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 2000
          description: Pre-registered OAuth callback URLs for this app
    register_api_key_request_body:
      type: object
      required:
      - api_secret
      properties:
        api_secret:
          type: string
          description: The API secret (private key hex) for the developer app
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 Authorization Code flow with PKCE for third-party applications.


        Allows apps to authenticate users and obtain access tokens scoped to read or read+write permissions on behalf of the user.


        **Scopes:**

        - `read` — Read-only access to the user''s public and private data.

        - `write` — Read and write access, allowing mutations on behalf of the user.


        **PKCE Required:**

        All authorization code requests must include `code_challenge` and `code_challenge_method=S256` parameters.

        '
      flows:
        authorizationCode:
          authorizationUrl: /v1/oauth/authorize
          tokenUrl: /v1/oauth/token
          scopes:
            read: Read-only access to user data
            write: Read and write access on behalf of the user
    BasicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic Authentication with Ethereum private key for write operations.


        **Authentication**


        Use HTTP Basic Authentication where the password field contains your Ethereum private key:

        ```

        Authorization: Basic <base64(username:privatekey)>

        ```


        The username can be any value. The password must be your Ethereum private key in hex format (with or without 0x prefix).


        Example:

        ```

        Authorization: Basic dXNlcm5hbWU6MHgxMjM0NTY3ODkwYWJjZGVmLi4u

        ```


        **How it works:**

        1. The API decodes the Basic Auth credentials

        2. Extracts the private key from the password field

        3. Derives the Ethereum address from the private key

        4. Uses this address for authorization checks


        **Authorization**


        The derived wallet address must be either:

        - The wallet of the user being acted upon (direct ownership)

        - A wallet with an approved, non-revoked grant for the user (manager mode)

        '
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The API bearer token or OAuth JWT token for the user.

        '
x-original-swagger-version: '2.0'