Auphonic Services API

openapi: 3.2.0
info:
  title: Auphonic Services API
  description: 'The Auphonic REST API allows you to integrate audio post production services

    and algorithms into your scripts, external workflows and third-party applications.'
  contact:
    email: support@auphonic.com
    url: https://auphonic.com
servers:
- url: https://auphonic.com
  description: Auphonic Production Server
security:
- bearerAuth: []
- basicAuth: []
- oauth2: []
tags:
- name: Services
  description: 'Manage external service integrations.


    See the External Services documentation for details.'
paths:
  /api/services.json:
    get:
      tags:
      - Services
      summary: List all external services
      description: 'Returns all registered external services (Dropbox, FTP, SFTP, YouTube,

        SoundCloud, etc.) of the authenticated user. Each service has a type-specific

        set of fields.


        See the external services documentation for details.'
      operationId: listServices
      responses:
        '200':
          description: List of services
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponseEnvelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/ServiceAccount'
              example:
                status_code: 200
                error_code: null
                error_message: ''
                form_errors: {}
                data:
                - uuid: AbCdEfGhIjKlMnOpQrStUv
                  display_name: My Dropbox
                  type: dropbox
                  incoming: true
                  outgoing: true
                  email: user@example.com
                - uuid: WxYzAbCdEfGhIjKlMnOpQr
                  display_name: Production Server
                  type: sftp
                  incoming: true
                  outgoing: true
                  host: sftp.example.com
                  port: 22
                  path: /uploads
                  base_url: https://cdn.example.com/uploads
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/service/{uuid}/ls.json:
    get:
      tags:
      - Services
      summary: List files on external service
      description: 'Returns a list of all supported audio and video files on the external

        service with the given UUID.


        **Rate limit:** 10 requests per minute (40 for business accounts). Returns 429 if exceeded.


        See the list files documentation for details.'
      operationId: listServiceFiles
      parameters:
      - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponseEnvelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: string
                      example:
                      - my_audio.mp3
                      - my_video.avi
                      - next_file.ogg
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/service/connect.json:
    post:
      tags:
      - Services
      summary: Connect external webhook service
      description: 'Register an external webhook service. Only available via OAuth2 authentication.

        Used by third-party services to register as publishing targets within Auphonic.


        The webhook receives production data as a signed JWT. Verify the JWT signature

        using the OAuth2 client secret.


        See the External Services documentation for details.'
      operationId: connectService
      security:
      - oauth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - display_name
              - webhook_url
              properties:
                display_name:
                  type: string
                  description: Display name for the service
                webhook_url:
                  type: string
                  format: uri
                  description: Webhook URL that receives production data
                custom_data:
                  type: string
                  description: Custom data to include with webhook calls
      responses:
        '200':
          description: Service connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseEnvelope'
          example:
            status_code: 401
            error_code: null
            error_message: Authentication required
            form_errors: {}
            data: {}
    BadRequest:
      description: Bad request - validation errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseEnvelope'
          example:
            status_code: 400
            error_code: null
            error_message: Validation failed
            form_errors:
              metadata:
              - This field is required.
            data: {}
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseEnvelope'
          example:
            status_code: 429
            error_code: null
            error_message: Too many requests
            form_errors: {}
            data: {}
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseEnvelope'
          example:
            status_code: 404
            error_code: null
            error_message: Not found
            form_errors: {}
            data: {}
  schemas:
    ServiceAccount:
      type: object
      description: 'An external service account registered by the user.

        Fields present depend on the service `type`.

        Query `/api/info/service_types.json` for available service types and their parameters.

        Common fields (uuid, display_name, type, incoming, outgoing) are always present.

        Type-specific fields (email, host, port, path, bucket, etc.) are only present for

        applicable service types.

        '
      properties:
        uuid:
          type: string
        display_name:
          type: string
        type:
          type: string
          description: Service type identifier
        incoming:
          type: boolean
        outgoing:
          type: boolean
        email:
          type: string
        host:
          type: string
        port:
          type: integer
        path:
          type: string
        base_url:
          type: string
        permissions:
          type: string
        bucket:
          type: string
        key_prefix:
          type: string
        canned_acl:
          type: string
        endpoint:
          type: string
        program_keyword:
          type: string
        url:
          type: string
          description: WebDAV URL
        libsyn_show_slug:
          type: string
        libsyn_directory:
          type: string
        podcast:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
    ApiResponseEnvelope:
      type: object
      properties:
        status_code:
          type: integer
          description: HTTP status code
          example: 200
        error_code:
          type:
          - string
          - 'null'
          description: Error code identifier, null on success
        error_message:
          type: string
          description: Human-readable error message, empty on success
          example: ''
        form_errors:
          type: object
          description: Field-level validation errors
          additionalProperties:
            type: array
            items:
              type: string
        data:
          description: Response payload (varies per endpoint)
      required:
      - status_code
      - error_code
      - error_message
      - form_errors
      - data
  parameters:
    uuid:
      name: uuid
      in: path
      required: true
      description: UUID of the resource (22-character alphanumeric string)
      schema:
        type: string
        pattern: ^[a-zA-Z0-9]{22}$
        example: KKw7AxpLrDBQKLVnQCBtCh
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API Key or OAuth2 access token. Use header `Authorization: Bearer {token}`

        or query parameter `?bearer_token={token}`.

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with Auphonic username and password.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for third-party applications.
      flows:
        authorizationCode:
          authorizationUrl: https://auphonic.com/oauth2/authorize/
          tokenUrl: https://auphonic.com/oauth2/token/
          scopes: {}
        password:
          tokenUrl: https://auphonic.com/oauth2/token/
          scopes: {}