openapi: 3.2.0
info:
  title: wazo-confd External Apps API
  description: "Confd exposes an API for managing core resources on a Wazo server such as users, extensions, devices, voicemails, queues, etc. Resources can be associated together to provide additional functionality. For example: By associating a voicemail with a user, calls will automatically fallback on to the voicemail when the user cannot answer.\n\nImplementation notes\n====================\n\nErrors\n------\n\nResponses containing errors will have a status code in the 400 or 500 class. A list of error messages will be returned in the body of the response as a JSON-encoded array:\n\n~~~\n[\n    \"Input error - User not found\",\n    \"Resource error - User not associated to a line\"\n]\n~~~\n\n\nUpdating resources via PUT\n--------------------------\n\nWhen updating a resource, all fields become optional. In other words, only values that have been changed need to be sent to the server. Please note that this behavior may change in future versions of the API."
  version: '1.1'
  license:
    name: GPL v3
    url: http://www.gnu.org/licenses/gpl.txt
  contact:
    name: Wazo Dev Team
    url: https://wazo-platform.org/
    email: dev@wazo.community
  x-logo:
    url: https://wazo-platform.org/images/logo-black.svg
    backgroundColor: '#FAFAFA'
    altText: Wazo Logo
servers:
- url: /1.1
security:
- wazo_auth_token: []
tags:
- name: external_apps
paths:
  /external/apps:
    get:
      operationId: list_external_apps
      summary: List external apps
      description: '**Required ACL:** `confd.external.apps.read`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/recurse'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: External apps list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAppItems'
  /external/apps/{app_name}:
    post:
      operationId: create_external_app
      summary: Create external app
      description: '**Required ACL:** `confd.external.apps.{app_name}.create`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '201':
          description: External app created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApp'
        '400':
          $ref: '#/components/responses/CreateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalApp'
        description: External app to create
        required: true
    get:
      operationId: get_external_app
      summary: Get external app
      description: '**Required ACL:** `confd.external.apps.{app_name}.read`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '200':
          description: External App
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApp'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: update_external_app
      summary: Update external app
      description: '**Required ACL:** `confd.external.apps.{app_name}.update`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalApp'
        required: true
    delete:
      operationId: delete_external_app
      summary: Delete external app
      description: '**Required ACL:** `confd.external.apps.{app_name}.delete`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '204':
          $ref: '#/components/responses/ResourceDeleted'
        '400':
          $ref: '#/components/responses/DeleteError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /users/{user_uuid}/external/apps:
    get:
      operationId: list_user_external_apps
      summary: List user external apps
      description: '**Required ACL:** `confd.users.{user_uuid}.external.apps.read`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/useruuid'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/user_external_app_view'
      responses:
        '200':
          description: User external apps list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserExternalAppItems'
  /users/{user_uuid}/external/apps/{app_name}:
    post:
      operationId: create_user_external_app
      summary: Create user external app
      description: '**Required ACL:** `confd.users.{user_uuid}.external.apps.{app_name}.create`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/useruuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '201':
          description: External app created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserExternalApp'
        '400':
          $ref: '#/components/responses/CreateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserExternalApp'
        description: External app to create
        required: true
    get:
      operationId: get_user_external_app
      summary: Get user external app
      description: '**Required ACL:** `confd.users.{user_uuid}.external.apps.{app_name}.read`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/useruuid'
      - $ref: '#/components/parameters/externalappname'
      - $ref: '#/components/parameters/user_external_app_view'
      responses:
        '200':
          description: External App
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserExternalApp'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: update_user_external_app
      summary: Update user external app
      description: '**Required ACL:** `confd.users.{user_uuid}.external.apps.{app_name}.update`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/useruuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserExternalApp'
        required: true
    delete:
      operationId: delete_user_external_app
      summary: Delete user external app
      description: '**Required ACL:** `confd.users.{user_uuid}.external.apps.{app_name}.delete`'
      tags:
      - external_apps
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/useruuid'
      - $ref: '#/components/parameters/externalappname'
      responses:
        '204':
          $ref: '#/components/responses/ResourceDeleted'
        '400':
          $ref: '#/components/responses/DeleteError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  responses:
    NotFoundError:
      description: The resource requested was not found on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceDeleted:
      description: Resource was deleted successfully
    ResourceUpdated:
      description: Resource was updated successfully
    CreateError:
      description: An error occurred when creating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpdateError:
      description: An error occurred when updating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    DeleteError:
      description: An error occurred when deleting the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    tenantuuid:
      name: Wazo-Tenant
      in: header
      description: The tenant's UUID, defining the ownership of a given resource.
      required: false
      schema:
        type: string
    useruuid:
      required: true
      name: user_uuid
      in: path
      description: the user's UUID
      schema:
        type: string
        format: uuid
    user_external_app_view:
      required: false
      name: view
      in: query
      description: 'Different view of the external app endpoint


        The `default` view, when the argument is omitted, is to return the user value for this

        external app


        The `fallback` view return the user value for this external app, but if not found, will

        fallback to the tenant configured value


        **WARNING**: Using fallback view on list will disabled all pagination and search features

        '
      schema:
        type: string
        enum:
        - fallback
    offset:
      required: false
      name: offset
      in: query
      description: Number of items to skip over in the list. Useful for pagination.
      schema:
        type: integer
    order:
      required: false
      name: order
      in: query
      description: Name of the field to use for sorting the list of items returned.
      schema:
        type: string
    externalappname:
      required: true
      name: app_name
      in: path
      description: External App's name
      schema:
        type: string
    direction:
      required: false
      name: direction
      in: query
      description: Sort list of items in 'asc' (ascending) or 'desc' (descending) order
      schema:
        type: string
        enum:
        - asc
        - desc
    recurse:
      name: recurse
      in: query
      description: Should the query include sub-tenants
      required: false
      schema:
        type: boolean
        default: false
    search:
      required: false
      name: search
      in: query
      description: Search term for filtering a list of items. Only items with a field containing the search term will be returned.
      schema:
        type: string
    limit:
      required: false
      name: limit
      in: query
      description: Maximum number of items to return in the list
      schema:
        type: integer
  schemas:
    ExternalAppItems:
      title: ExternalAppItems
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExternalApp'
        total:
          type: integer
      required:
      - total
    ExternalApp:
      title: ExternalApp
      properties:
        tenant_uuid:
          type: string
          description: The UUID of the tenant
          readOnly: true
        name:
          type: string
          description: The name to identify the external app
          readOnly: true
        label:
          type: string
          description: The label of the external app
        configuration:
          type: object
          description: Arbitrary settings needed by an external app
    UserExternalApp:
      title: UserExternalApp
      properties:
        name:
          type: string
          description: The name to identify the external app
          readOnly: true
        label:
          type: string
          description: The label of the external app
        configuration:
          type: object
          description: Arbitrary settings needed by an external app
    UserExternalAppItems:
      title: UserExternalAppItems
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserExternalApp'
        total:
          type: integer
      required:
      - total
    Error:
      type: array
      items:
        type: string
  securitySchemes:
    wazo_auth_token:
      type: apiKey
      name: X-Auth-Token
      in: header
x-xivo-port: 9486
x-xivo-name: confd
x-apievangelist-source:
  harvested_from: https://github.com/wazo-platform/wazo-confd
  assembly: base plugin api.yml deep-merged with all plugin api.yml fragments, reproducing what the running service serves at /api/confd/1.1/api/api.yml (see wazo_confd/plugins/api/http.py — xivo.chain_map.ChainMap)
  spec_version: Swagger 2.0 (as published by Wazo)
  harvested: '2026-08-17'