Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
700 lines (688 sloc) 30.3 KB
---
openapi: "3.0.0"
info:
version: 2.0.4
title: "Application API"
description: |
Nexmo provides an Application API to allow management of your Nexmo Applications.
This API is backwards compatible with version 1. Applications created using version 1 of the API can also be managed using version 2 (this version) of the API.
contact:
name: Nexmo
url: 'https://developer.nexmo.com/'
email: devrel@nexmo.com
servers:
- url: https://api.nexmo.com
security:
- basicAuth: []
paths:
/v2/applications:
post:
summary: Create an application
operationId: createApplication
requestBody:
required: true
content:
application/json:
schema:
required:
- name
properties:
name:
description: "Application Name"
example: "Demo Application"
type: "string"
keys:
type: object
properties:
public_key:
type: string
example: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
description: Public key
capabilities:
type: object
description: "Your application can use multiple products. This contains the configuration for each product. This replaces the application `type` from version 1 of the Application API."
x-nexmo-developer-collection-description-shown: true
properties:
voice:
type: object
description: "Voice application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
answer_url:
type: object
description: "The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/answer
http_method:
type: string
example: GET
enum:
- GET
- POST
fallback_answer_url:
type: object
description: |
If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
`fallback_answer_url` if it is set. This URL must return an NCCO.
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://fallback.example.com/webhooks/answer
http_method:
type: string
example: GET
enum:
- GET
- POST
event_url:
type: object
description: "Nexmo will send call events (e.g. `ringing`, `answered`) to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
rtc:
type: object
description: "RTC / Client SDK application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
event_url:
type: object
description: "Nexmo will send RTC events to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
messages:
type: object
description: "Messages and Dispatch application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
inbound_url:
type: object
description: "Nexmo will forward inbound messages to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/inbound
http_method:
type: string
example: POST
enum:
- POST
status_url:
type: object
description: "Nexmo will send message status updates (e.g. `delivered`, `seen`) to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/status
http_method:
type: string
example: POST
enum:
- POST
vbc:
type: object
description: "Specify `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object."
x-nexmo-developer-collection-description-shown: true
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApplicationResponse'
- type: object
properties:
keys:
type: object
properties:
public_key:
type: string
example: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
private_key:
type: string
example: |
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFA
ASCBKcwggSjAgEAAoIBAQDEPpvi+3
RH1efQ\nkveWzZDrNNoEXmBw61w+O
0u/N36tJnN5XnYecU64yHzu2ByEr0
7iIvYbavFnADwl\nHMTJwqDQakpa3
8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
uJPgZD7OVB69oYOV92vIIJ7JLYwqb
-----END PRIVATE KEY-----
'400':
$ref: '#/components/responses/InvalidPayloadError'
'401':
$ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
'405':
$ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
'406':
$ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
'415':
$ref: 'common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader'
get:
operationId: listApplication
summary: List available applications
parameters:
- name: page_size
in: query
description: The number of applications per page
schema:
type: integer
- name: page
in: query
description: The current page number (starts at 1)
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
page_size:
type: integer
example: 10
description: The number of applications per page
page:
type: integer
example: 1
description: The current page number (starts at 1)
total_items:
type: integer
example: 6
description: The total number of applications
total_pages:
type: integer
example: 1
description: The total number of pages returned
_embedded:
type: object
description: A list of applications matching your existing filters
properties:
applications:
type: array
items:
$ref: '#/components/schemas/ApplicationResponse'
'400':
description: Invalid Request
content:
application/json:
schema:
properties:
type:
type: string
example: 'https://developer.nexmo.com/api-errors/application#list-validation'
title:
type: string
example: Bad Request
detail:
type: string
example: The request failed due to validation errors
invalid_parameters:
type: array
items:
type: object
properties:
name:
type: string
example: page_size
reason:
type: string
example: must be between 1 and 100
instance:
$ref: 'common/common_errors.yml#/components/fields/instance'
'401':
$ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
'405':
$ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
'406':
$ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
/v2/applications/{id}:
parameters:
- name: id
in: path
required: true
description: The ID of the application
example: 78d335fa323d01149c3dd6f0d48968cf
schema:
type: string
get:
operationId: getApplication
summary: Get an application
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
'401':
$ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
'404':
$ref: 'common/common_errors.yml#/components/responses/NotFoundError'
'405':
$ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
'406':
$ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
put:
summary: Update an application
operationId: updateApplication
requestBody:
required: true
content:
application/json:
schema:
required:
- name
properties:
name:
description: "Application Name"
example: "Demo Application"
type: "string"
keys:
type: object
properties:
public_key:
type: string
example: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
description: Public key
capabilities:
type: object
description: "Your application can use multiple products. This contains the configuration for each product. This replaces the application `type` from version 1 of the Application API."
x-nexmo-developer-collection-description-shown: true
properties:
voice:
type: object
description: "Voice application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
answer_url:
type: object
description: "The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/answer
http_method:
type: string
example: GET
enum:
- GET
- POST
fallback_answer_url:
type: object
description: |
If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
`fallback_answer_url` if it is set. This URL must return an NCCO
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://fallback.example.com/webhooks/answer
http_method:
type: string
example: GET
enum:
- GET
- POST
event_url:
type: object
description: "Nexmo will send call events (e.g. `ringing`, `answered`) to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
rtc:
type: object
description: "RTC / Client SDK application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
event_url:
type: object
description: "Nexmo will send RTC events to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
messages:
type: object
description: "Messages and Dispatch application webhook config"
x-nexmo-developer-collection-description-shown: true
properties:
webhooks:
type: object
properties:
inbound_url:
type: object
description: "Nexmo will forward inbound messages to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/inbound
http_method:
type: string
example: POST
enum:
- POST
status_url:
type: object
description: "Nexmo will send message status updates (e.g. `delivered`, `seen`) to this URL"
x-nexmo-developer-collection-description-shown: true
properties:
address:
type: string
example: https://example.com/webhooks/status
http_method:
type: string
example: POST
enum:
- POST
vbc:
type: object
description: "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object."
x-nexmo-developer-collection-description-shown: true
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApplicationResponse'
- type: object
properties:
keys:
type: object
properties:
public_key:
type: string
example: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
private_key:
type: string
example: |
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFA
ASCBKcwggSjAgEAAoIBAQDEPpvi+3
RH1efQ\nkveWzZDrNNoEXmBw61w+O
0u/N36tJnN5XnYecU64yHzu2ByEr0
7iIvYbavFnADwl\nHMTJwqDQakpa3
8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
uJPgZD7OVB69oYOV92vIIJ7JLYwqb
-----END PRIVATE KEY-----
'400':
$ref: '#/components/responses/InvalidPayloadError'
'401':
$ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
'404':
$ref: 'common/common_errors.yml#/components/responses/NotFoundError'
'405':
$ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
'406':
$ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
'415':
$ref: 'common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader'
delete:
operationId: deleteApplication
summary: Delete an application
description: Deleting an application **cannot be undone**.
responses:
'204':
description: Success
'401':
$ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
'404':
$ref: 'common/common_errors.yml#/components/responses/NotFoundError'
'405':
$ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
'406':
$ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
responses:
InvalidPayloadError:
description: Invalid Request
content:
application/json:
schema:
properties:
type:
type: string
example: 'https://developer.nexmo.com/api-errors/application#payload-validation'
title:
type: string
example: Bad Request
detail:
type: string
example: The request failed due to validation errors
invalid_parameters:
type: array
items:
type: object
properties:
name:
type: string
example: capabilities.voice.webhooks.answer_url.http_method
reason:
type: string
example: 'must be one of: GET, POST'
instance:
$ref: 'common/common_errors.yml#/components/fields/instance'
schemas:
ApplicationResponse:
properties:
id:
type: string
example: 78d335fa323d01149c3dd6f0d48968cf
description: The application's ID
name:
type: string
example: My Application
description: Friendly identifier for your application. This is not unique
capabilities:
type: object
description: Configuration for the products available in this application
properties:
voice:
type: object
description: Voice related configuration
properties:
webhooks:
type: object
properties:
answer_url:
type: object
properties:
address:
type: string
example: https://example.com/webhooks/answer
description: The URL that Nexmo requests when a call is placed/received. Must return an NCCO
http_method:
type: string
example: POST
description: The HTTP method used to fetch your NCCO from your `answer_url`
fallback_answer_url:
type: object
properties:
address:
type: string
example: https://fallback.example.com/webhooks/answer
description: |
If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
`fallback_answer_url` if it is set. This URL must return an NCCO.
http_method:
type: string
example: POST
description: The HTTP method used to fetch your NCCO from your `answer_url`
event_url:
type: object
properties:
address:
type: string
example: https://example.com/webhooks/event
description: The URL that Nexmo sends events related to your call to
http_method:
type: string
example: POST
description: The HTTP method used to send events to your server
messages:
type: object
description: Messages / Dispatch related configuration
properties:
webhooks:
type: object
properties:
inbound_url:
type: object
properties:
address:
type: string
example: https://example.com/webhooks/inbound
description: The URL that Nexmo forwards inbound messages to on your server
http_method:
type: string
example: POST
description: The HTTP method used to send inbound messages to your server
status_url:
type: object
properties:
address:
type: string
example: https://example.com/webhooks/status
description: The URL that Nexmo sends events related to your messages to
http_method:
type: string
example: POST
description: The HTTP method used to send events to your server (always `POST`)
rtc:
type: object
description: RTC / Conversation Service related configuration
properties:
webhooks:
type: object
properties:
event_url:
type: object
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
vbc:
type: object
description: "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object."
x-errors:
payload-validation:
description: Invalid request. See `invalid_parameters` field for details
resolution: Review the documentation and send a valid `POST` request.
link:
text: View API reference
url: /api/application.v2#createApplication
list-validation:
description: Invalid request. See `invalid_parameters` field for details
resolution: Review the documentation and send a valid `GET` request.
link:
text: View API reference
url: /api/application.v2#listApplication
rate-limit:
description: The request was rate limited
resolution: The Redact API supports 170 requests per second. Reduce the frequency of your requests.
You can’t perform that action at this time.