openapi: 3.0.0
info:
  title: Nexmo Application API
  version: 1.0.2
  description: >-
    <div class="Vlt-callout Vlt-callout--critical">
    <i></i>
    <div class="Vlt-callout__content">
      <h4>Applications V1 is deprecated</h4>
      This version of the API has been deprecated. Please use <a href="/api/application.v2">version 2</a> going forwards
    </div>
    </div>

    A Nexmo application contains the security and configuration information you
    need to connect to Nexmo endpoints and easily use our products.
  contact:
    name: Nexmo.com
    email: devrel@nexmo.com
    url: "https://developer.nexmo.com/"
    x-twitter: Nexmo
  termsOfService: "https://www.nexmo.com/terms-of-use"
  license:
    name: The MIT License (MIT)
    url: "https://opensource.org/licenses/MIT"
  x-logo:
    url: "https://twitter.com/Nexmo/profile_image?size=original"
  x-apiClientRegistration: "https://dashboard.nexmo.com/sign-up"
servers:
  - url: "https://api.nexmo.com/v1/applications"
externalDocs:
  url: "https://developer.nexmo.com/api/developer/application"
  x-sha1: d8836c374e2a7504bd2cd59e05fcee440f67cb44
paths:
  /:
    get:
      summary: Retrieve all Applications
      description: >-
        You use a `GET` request to retrieve details of all applications
        associated with your account.
      operationId: retrieveApplications
      parameters:
        - $ref: "#/components/parameters/apiKeyQueryString"
        - $ref: "#/components/parameters/apiSecretQueryString"
        - name: page_size
          required: false
          in: query
          description: >-
            Set the number of items returned on each call to this endpoint. The
            default is 10 records.
          schema:
            type: integer
            default: 10
          example: 10
        - name: page_index
          required: false
          in: query
          description: Set the offset from the first page. The default value is `0`.
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applications"
    post:
      summary: Create Application
      description: You use a `POST` request to create a new application.
      operationId: createApplication
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
                - api_secret
                - name
                - type
              properties:
                api_key:
                  $ref: "#/components/schemas/apiKey"
                api_secret:
                  $ref: "#/components/schemas/apiSecret"
                name:
                  description: The name of your application.
                  type: string
                  example: My Application
                type:
                  description: >-
                    The Nexmo product or products that you access with this
                    application. Currently `voice` and `messages` application types are supported.
                  type: string
                  example: voice
                  enum:
                    - voice
                    - messages
                answer_url:
                  description: >-
                    The URL where your webhook delivers the Nexmo Call Control
                    Object that governs this call. As soon as your user answers
                    a call Nexmo makes a request to `answer_url`. Required for inbound calls only.
                  type: string
                  example: "https://example.com/webhooks/answer"
                answer_method:
                  description: >-
                    The HTTP method used to make the request to `answer_url`.
                    The default value is `GET`.
                  type: string
                  example: GET
                event_url:
                  description: >-
                    Nexmo sends event information asynchronously to this URL
                    when status changes for `voice` applications. Always required for `voice` applications.
                  type: string
                  example: "https://example.com/webhooks/event"
                event_method:
                  description: >-
                    The HTTP method used to send event information to `event_url`.
                    The default value is `POST`. For `voice` type applications only.
                  type: string
                  example: POST
                status_url:
                  description: >-
                    Nexmo sends event information asynchronously to this URL
                    when status changes. Required for `messages` type applications only.
                  type: string
                  example: "https://example.com/webhooks/status"
                status_method:
                  description: >-
                    The HTTP method used to send event information to `status_url`.
                    The default value is `POST`. For `messages` type applications only.
                  type: string
                  example: POST
                inbound_url:
                  description: >-
                    Nexmo sends a request to this URL when an inbound message
                    is received. Required for `messages` type applications only.
                  type: string
                  example: "https://example.com/webhooks/inbound"
                inbound_method:
                  description: >-
                    The HTTP method used to send event information to `inbound_url`.
                    The default value is `POST`. For `messages` type applications only.
                  type: string
                  example: POST
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationCreated"

  "/{app_id}":
    get:
      summary: Retrieve Application
      description: You use a `GET` request to retrieve details about a single application.
      operationId: retrieveApplication
      parameters:
        - $ref: "#/components/parameters/apiKeyQueryString"
        - $ref: "#/components/parameters/apiSecretQueryString"
        - $ref: "#/components/parameters/app_id"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/application"
    put:
      summary: Update Application
      description: You use a `PUT` request to update an existing application.
      operationId: updateApplication
      parameters:
        - $ref: "#/components/parameters/app_id"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
                - api_secret
                - name
                - type
              properties:
                api_key:
                  $ref: "#/components/schemas/apiKey"
                api_secret:
                  $ref: "#/components/schemas/apiSecret"
                name:
                  description: The name of your application.
                  type: string
                  example: UpdatedApplication
                type:
                  description: >-
                    The Nexmo product or products that you access with this application.
                    Currently `voice` and `messages` application types are supported. You 
                    can't change the type of application.
                  type: string
                  enum:
                    - voice
                    - messages
                  example: voice
                answer_url:
                  description: >-
                    The URL where your webhook delivers the Nexmo Call Control Object
                    that governs this call. As soon as your user answers a call Nexmo
                    makes a request to `answer_url`.
                  type: string
                  format: url
                  example: "https://example.com/webhooks/answer"
                answer_method:
                  description: >-
                    The HTTP method used to make the request to `answer_url`. The
                    default value is `GET`.
                  type: string
                  default: GET
                  example: GET
                event_url:
                  description: >-
                    Nexmo sends event information asynchronously to this URL when status
                    changes.
                  type: string
                  format: url
                  example: "https://example.com/webhooks/event"
                event_method:
                  description: >-
                    The HTTP method used to send event information to `event_url`. The
                    default value is POST.
                  type: string
                  default: POST
                  example: POST
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/application"
    delete:
      summary: Destroy Application
      description: You use a `DELETE` request to delete a single application.
      operationId: deleteApplication
      parameters:
        - $ref: "#/components/parameters/app_id"
      responses:
        "204":
          description: No content
components:
  parameters:
    app_id:
      name: app_id
      in: path
      required: true
      description: The ID allocated to your application by Nexmo.
      schema:
        type: string
      example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    apiKeyQueryString:
      schema:
        type: string
      name: api_key
      in: query
      required: true
      description: >-
        You can find your API key in your [account
        overview](https://dashboard.nexmo.com/account-overview)
    apiSecretQueryString:
      schema:
        type: string
      name: api_secret
      in: query
      required: true
      description: >-
        You can find your API secret in your [account
        overview](https://dashboard.nexmo.com/account-overview)

  schemas:
    apiKey:
      type: string
      description: >-
        You can find your API key in your [account
        overview](https://dashboard.nexmo.com/account-overview)
      example: ap1k3y
    apiSecret:
      type: string
      description: >-
        You can find your API secret in your [account
        overview](https://dashboard.nexmo.com/account-overview)
      example: 230e6cf0709417176df1b4fc1e083adc
    links:
      type: object
      description: >-
        A series of links between resources in this API in the following [HAL
        specification](http://stateless.co/hal_specification.html).
      properties:
        href:
          type: string
          format: url
          description: The link URL.
          example: /v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    voice:
      description: >-
        The Nexmo product that you access with this application.
      type: object
      properties:
        webhooks:
          type: array
          items:
            type: object
            required:
              - endpoint_type
              - endpoint
              - http_method
            properties:
              endpoint_type:
                type: string
                enum:
                  - answer_url
                  - event_url
                example: answer_url
              endpoint:
                type: string
                description: >-
                  `answer_url`: The URL where your webhook delivers the Nexmo
                  Call Control Object that governs this call. As soon as your
                  user answers a call Nexmo makes a request to answer_url.
                  `event_url`: Nexmo sends event information asynchronously to
                  this URL when status changes.
                format: url
                example: "https://example.com/webhooks/answer"
              http_method:
                type: string
                description: >-
                  The HTTP method used to send event information to the
                  `event_url` or `answer_url`.
                enum:
                  - GET
                  - POST
                example: GET
    messages:
      description: >-
        The Nexmo product that you access with this application.
      type: object
      properties:
        webhooks:
          type: array
          items:
            type: object
            required:
              - endpoint_type
              - endpoint
              - http_method
            properties:
              endpoint_type:
                type: string
                enum:
                  - inbound_url
                  - status_url
                example: status_url
              endpoint:
                type: string
                description: >-
                  `inbound_url`: The URL where inbound messages are delivered.
                  `status_url`: The URL where message status is delivered.
                format: url
                example: "https://example.com/webhooks/status"
              http_method:
                type: string
                description: >-
                  The HTTP method used to send data to the
                  `inbound_url` or `status_url`. Default is POST.
                enum:
                  - GET
                  - POST
                example: POST
    keys:
      description: >-
        The Nexmo product that you access with this application.
      type: object
      properties:
        public_key:
          description: >-
            The public key used to validate the
            [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token).
          type: string
          example: PUBLIC_KEY
    keysWithPrivateKey:
      allOf:
        - $ref: "#/components/schemas/keys"
        - properties:
            private_key:
              description: >-
                The private key you use to generate the JSON Web Token (JWT)
                that authenticates your requests to Messages API.
              type: string
              example: PRIVATE_KEY
    applicationCreated:
      allOf:
        - $ref: "#/components/schemas/application"
        - properties:
            keys:
              $ref: "#/components/schemas/keysWithPrivateKey"
    application:
      type: object
      required:
        - name
        - voice
        - messages
      properties:
        id:
          $ref: "#/components/schemas/applicationBase/properties/id"
        name:
          $ref: "#/components/schemas/applicationBase/properties/name"
        voice:
          $ref: "#/components/schemas/voice"
        messages:
          $ref: "#/components/schemas/messages"
        keys:
          $ref: "#/components/schemas/keys"
        _links:
          $ref: "#/components/schemas/links"
    applicationBase:
      type: object
      properties:
        id:
          description: The ID allocated to your application by Nexmo.
          type: string
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        name:
          description: The name of your application
          type: string
          example: My Application
    applications:
      type: object
      required:
        - count
        - page_size
        - page_index
        - _embedded
        - _links
      properties:
        count:
          $ref: "#/components/schemas/applicationsBase/properties/count"
        page_size:
          $ref: "#/components/schemas/applicationsBase/properties/page_size"
        page_index:
          $ref: "#/components/schemas/applicationsBase/properties/page_index"
        _embedded:
          $ref: "#/components/schemas/applicationsBase/properties/_embedded"
        _links:
          $ref: "#/components/schemas/links"
    applicationsBase:
      properties:
        count:
          description: The number of items associated with your account.
          type: integer
          example: 1
        page_size:
          description: >-
            The number of items returned on each call to this endpoint. The
            default is 10 records.
          type: integer
          example: 10
        page_index:
          description: The offset from the first page.
          type: integer
          example: 1
        _embedded:
          type: object
          properties:
            applications:
              type: array
              description: >-
                The collection of your applications. Each object contains
                information about an an individual application. The public_key
                is not included in the application information.
              items:
                $ref: "#/components/schemas/application"