openapi: 3.0.0
servers:
  - url: https://api.nexmo.com/v1/applications
info:
  contact:
    email: devrel@nexmo.com
    name: Nexmo.com
    url: https://developer.nexmo.com/
    x-twitter: Nexmo
  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.
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Nexmo Application API
  version: 1.0.2
  x-apiClientRegistration: https://dashboard.nexmo.com/sign-up
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/application.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: application
externalDocs:
  url: https://developer.nexmo.com/api/developer/application
  x-sha1: d8836c374e2a7504bd2cd59e05fcee440f67cb44
paths:
  /:
    get:
      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"
        - description: Set the number of items returned on each call to this endpoint. The default is 10 records.
          example: 10
          in: query
          name: page_size
          required: false
          schema:
            default: 10
            type: integer
        - description: Set the offset from the first page. The default value is `0`.
          example: 0
          in: query
          name: page_index
          required: false
          schema:
            default: 0
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applications"
          description: OK
      summary: Retrieve all Applications
    post:
      description: You use a `POST` request to create a new application.
      operationId: createApplication
      requestBody:
        content:
          application/json:
            schema:
              properties:
                answer_method:
                  description: The HTTP method used to make the request to `answer_url`. The default value is `GET`.
                  example: GET
                  type: string
                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.
                  example: https://example.com/webhooks/answer
                  type: string
                api_key:
                  $ref: "#/components/schemas/apiKey"
                api_secret:
                  $ref: "#/components/schemas/apiSecret"
                event_method:
                  description: The HTTP method used to send event information to `event_url`. The default value is `POST`. For `voice` type applications only.
                  example: POST
                  type: string
                event_url:
                  description: Nexmo sends event information asynchronously to this URL when status changes for `voice` applications. Always required for `voice` applications.
                  example: https://example.com/webhooks/event
                  type: string
                inbound_method:
                  description: The HTTP method used to send event information to `inbound_url`. The default value is `POST`. For `messages` type applications only.
                  example: POST
                  type: string
                inbound_url:
                  description: Nexmo sends a request to this URL when an inbound message is received. Required for `messages` type applications only.
                  example: https://example.com/webhooks/inbound
                  type: string
                name:
                  description: The name of your application.
                  example: My Application
                  type: string
                status_method:
                  description: The HTTP method used to send event information to `status_url`. The default value is `POST`. For `messages` type applications only.
                  example: POST
                  type: string
                status_url:
                  description: Nexmo sends event information asynchronously to this URL when status changes. Required for `messages` type applications only.
                  example: https://example.com/webhooks/status
                  type: string
                type:
                  description: The Nexmo product or products that you access with this application. Currently `voice` and `messages` application types are supported.
                  enum:
                    - voice
                    - messages
                  example: voice
                  type: string
              required:
                - api_key
                - api_secret
                - name
                - type
              type: object
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationCreated"
          description: Created
      summary: Create Application
  /{app_id}:
    delete:
      description: You use a `DELETE` request to delete a single application.
      operationId: deleteApplication
      parameters:
        - $ref: "#/components/parameters/app_id"
      responses:
        "204":
          description: No content
      summary: Destroy Application
    get:
      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":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/application"
          description: OK
      summary: Retrieve Application
    put:
      description: You use a `PUT` request to update an existing application.
      operationId: updateApplication
      parameters:
        - $ref: "#/components/parameters/app_id"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                answer_method:
                  default: GET
                  description: The HTTP method used to make the request to `answer_url`. The default value is `GET`.
                  example: GET
                  type: string
                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`.
                  example: https://example.com/webhooks/answer
                  format: url
                  type: string
                api_key:
                  $ref: "#/components/schemas/apiKey"
                api_secret:
                  $ref: "#/components/schemas/apiSecret"
                event_method:
                  default: POST
                  description: The HTTP method used to send event information to `event_url`. The default value is POST.
                  example: POST
                  type: string
                event_url:
                  description: Nexmo sends event information asynchronously to this URL when status changes.
                  example: https://example.com/webhooks/event
                  format: url
                  type: string
                name:
                  description: The name of your application.
                  example: UpdatedApplication
                  type: string
                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.
                  enum:
                    - voice
                    - messages
                  example: voice
                  type: string
              required:
                - api_key
                - api_secret
                - name
                - type
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/application"
          description: OK
      summary: Update Application
components:
  parameters:
    apiKeyQueryString:
      description: You can find your API key in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_key
      required: true
      schema:
        type: string
    apiSecretQueryString:
      description: You can find your API secret in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_secret
      required: true
      schema:
        type: string
    app_id:
      description: The ID allocated to your application by Nexmo.
      example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      in: path
      name: app_id
      required: true
      schema:
        type: string
  schemas:
    apiKey:
      description: You can find your API key in your [account overview](https://dashboard.nexmo.com/account-overview)
      example: ap1k3y
      type: string
    apiSecret:
      description: You can find your API secret in your [account overview](https://dashboard.nexmo.com/account-overview)
      example: 230e6cf0709417176df1b4fc1e083adc
      type: string
    application:
      properties:
        _links:
          $ref: "#/components/schemas/links"
        id:
          $ref: "#/components/schemas/applicationBase/properties/id"
        keys:
          $ref: "#/components/schemas/keys"
        messages:
          $ref: "#/components/schemas/messages"
        name:
          $ref: "#/components/schemas/applicationBase/properties/name"
        voice:
          $ref: "#/components/schemas/voice"
      required:
        - name
        - voice
        - messages
      type: object
    applicationBase:
      properties:
        id:
          description: The ID allocated to your application by Nexmo.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        name:
          description: The name of your application
          example: My Application
          type: string
      type: object
    applicationCreated:
      allOf:
        - $ref: "#/components/schemas/application"
        - properties:
            keys:
              $ref: "#/components/schemas/keysWithPrivateKey"
    applications:
      properties:
        _embedded:
          $ref: "#/components/schemas/applicationsBase/properties/_embedded"
        _links:
          $ref: "#/components/schemas/links"
        count:
          $ref: "#/components/schemas/applicationsBase/properties/count"
        page_index:
          $ref: "#/components/schemas/applicationsBase/properties/page_index"
        page_size:
          $ref: "#/components/schemas/applicationsBase/properties/page_size"
      required:
        - count
        - page_size
        - page_index
        - _embedded
        - _links
      type: object
    applicationsBase:
      properties:
        _embedded:
          properties:
            applications:
              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"
              type: array
          type: object
        count:
          description: The number of items associated with your account.
          example: 1
          type: integer
        page_index:
          description: The offset from the first page.
          example: 1
          type: integer
        page_size:
          description: The number of items returned on each call to this endpoint. The default is 10 records.
          example: 10
          type: integer
    keys:
      description: The Nexmo product that you access with this application.
      properties:
        public_key:
          description: The public key used to validate the [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token).
          example: PUBLIC_KEY
          type: string
      type: object
    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.
              example: PRIVATE_KEY
              type: string
    links:
      description: A series of links between resources in this API in the following [HAL specification](http://stateless.co/hal_specification.html).
      properties:
        href:
          description: The link URL.
          example: /v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          format: url
          type: string
      type: object
    messages:
      description: The Nexmo product that you access with this application.
      properties:
        webhooks:
          items:
            properties:
              endpoint:
                description: "`inbound_url`: The URL where inbound messages are delivered. `status_url`: The URL where message status is delivered."
                example: https://example.com/webhooks/status
                format: url
                type: string
              endpoint_type:
                enum:
                  - inbound_url
                  - status_url
                example: status_url
                type: string
              http_method:
                description: The HTTP method used to send data to the `inbound_url` or `status_url`. Default is POST.
                enum:
                  - GET
                  - POST
                example: POST
                type: string
            required:
              - endpoint_type
              - endpoint
              - http_method
            type: object
          type: array
      type: object
    voice:
      description: The Nexmo product that you access with this application.
      properties:
        webhooks:
          items:
            properties:
              endpoint:
                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."
                example: https://example.com/webhooks/answer
                format: url
                type: string
              endpoint_type:
                enum:
                  - answer_url
                  - event_url
                example: answer_url
                type: string
              http_method:
                description: The HTTP method used to send event information to the `event_url` or `answer_url`.
                enum:
                  - GET
                  - POST
                example: GET
                type: string
            required:
              - endpoint_type
              - endpoint
              - http_method
            type: object
          type: array
      type: object
