{ "openapi": "3.0.3", "info": { "title": "Vonage QoD", "description": "Quality of Service on Demand API leveraging carrier QoS capabilities", "version": "0.2.1" }, "tags": [ { "name": "QoD Sessions", "description": "QoD session management services" } ], "servers": [ { "url": "https://api-eu.vonage.com" } ], "paths": { "/qod/v0.1/sessions": { "post": { "security": [ { "bearerAuth": [] } ], "tags": [ "QoD Sessions" ], "summary": "Create a QoD session", "operationId": "createQodSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSessionRequest" } } }, "required": true, "description": "" }, "callbacks": { "status-callback": { "/callbacks/qod/v0.1/session/status-update": { "post": { "summary": "QoD session status update callback", "description": "Provides updates on the status of the QoD session.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSessionStatusUpdateCallback" } } }, "required": true }, "responses": { "200": { "description": "Return this code if the server accepts the callback." }, "409": { "description": "Return this code if the server is not ready to accept the callback identifier, the request will be retried." } } } } } }, "responses": { "201": { "description": "QoD session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSession" } } } }, "401": { "description": "Authentication failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorUnauthorizedMissingCredentials" }, { "$ref": "#/components/schemas/ErrorUnauthorizedInvalidApplication" } ] } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorPaymentRequired" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorInvalidJson" }, { "$ref": "#/components/schemas/ErrorMsisdn" }, { "$ref": "#/components/schemas/ErrorDuration" }, { "$ref": "#/components/schemas/ErrorChannel" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorThrottled" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [], "description": "Enables applications to create a QoD session. The session represents the network flow(s) from the mobile device to the specified server(s) and the QoD profile(s) that will be applied to the network." }, "parameters": [] }, "/qod/v0.1/sessions/query": { "post": { "security": [ { "bearerAuth": [] } ], "tags": [ "QoD Sessions" ], "summary": "Query QoD sessions", "operationId": "queryQodSessions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSessionQueryRequest" } } }, "required": true, "description": "" }, "responses": { "200": { "description": "QoD session query response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QoDSession" } } } } }, "401": { "description": "Authentication failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorUnauthorizedMissingCredentials" }, { "$ref": "#/components/schemas/ErrorUnauthorizedInvalidApplication" } ] } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorPaymentRequired" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorInvalidJson" }, { "$ref": "#/components/schemas/ErrorMsisdn" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorThrottled" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [], "description": "Enables applications to create a QoD session. The session represents the network flow(s) from the mobile device to the specified server(s) and the QoD profile(s) that will be applied to the network." }, "parameters": [] }, "/qod/v0.1/sessions/{session_id}": { "get": { "security": [ { "bearerAuth": [] } ], "tags": [ "QoD Sessions" ], "summary": "Get QoD session by identifier", "operationId": "getQodSession", "parameters": [ { "$ref": "#/components/parameters/session_id" } ], "responses": { "200": { "description": "QoD session for the specified identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSession" } } } }, "401": { "description": "Authentication failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorUnauthorizedMissingCredentials" }, { "$ref": "#/components/schemas/ErrorUnauthorizedInvalidApplication" } ] } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorPaymentRequired" } } } }, "404": { "description": "Not Found or Forbidden Access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSessionNotFound" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorThrottled" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Enables applications to retrieve detailed information about a specific session." }, "delete": { "security": [ { "bearerAuth": [] } ], "tags": [ "QoD Sessions" ], "summary": "Cancel a QoD session", "operationId": "cancelQodSession", "parameters": [ { "$ref": "#/components/parameters/session_id" } ], "callbacks": { "status-callback": { "/callbacks/qod/v0.1/session/status-update": { "post": { "summary": "QoD status update callback", "description": "Provides updates on the status of the QoD session.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QoDSessionStatusUpdateCallback" } } }, "required": true }, "responses": { "200": { "description": "Return this code if the server accepts the callback." }, "409": { "description": "Return this code if the server is not ready to accept the callback identifier, the request will be retried." } } } } } }, "responses": { "204": { "description": "Session cancellation request accepted" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found or Forbidden Access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Enables applications to request the cancellation of a QoD session." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Duration": { "type": "integer", "description": "The requested session duration in seconds.", "minimum": 60, "maximum": 86400, "example": 60 }, "Msisdn": { "type": "string", "pattern": "^[1-9][0-9]{10,14}$", "minLength": 10, "maxLength": 15, "example": "14040000000", "description": "A single phone number you want insights on, starting with the country code. You may optionally include a leading +, but do not use 00 at the beginning. Ideally, the number should follow the [E.164](https://en.wikipedia.org/wiki/E.164) format. However, the API is designed to extract the phone number even if the input string contains alphanumeric characters, spaces, or symbols like brackets." }, "IpAddress": { "type": "string", "description": "IP address of the device, in IPv4 or IPv6 format. Note: not all mobile operators support both formats.", "example": "192.158.1.38", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)|([0-9a-fA-F]{1,4}:){7}([0-9a-fA-F]){1,4}|([0-9a-fA-F]{1,4}:){6}:[0-9a-fA-F]{1,4}|((([0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4})?::(([0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4})?)$" }, "Cidr": { "type": "string", "pattern": "^([01]?\\d\\d?|2[0-4]\\d|25[0-5])(?:\\.(?:[01]?\\d\\d?|2[0-4]\\d|25[0-5])){3}(\\/([0-9]|[1-2][0-9]|3[0-2]))?$|^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$|^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\\/.+)?$", "example": "2002::1234:abcd:ffff:c0a8:101/64", "description": "CIDR notation for IPv4 or IPv6 address ranges. Note: not all mobile operators support both formats." }, "Port": { "type": "integer", "format": "int32", "maximum": 65535, "minimum": 1, "nullable": true }, "DateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time in UTC" }, "QoDSessionQueryRequest": { "type": "object", "properties": { "msisdn": { "$ref": "#/components/schemas/Msisdn" }, "filter": { "type": "string", "enum": [ "in-progress", "all" ], "default": "in-progress", "description": "If set to `in-progress`, only in-progress sessions (e.g. PENDING, ACTIVE, CANCELLING) will be returned; otherwise all sessions will be returned." } } }, "QoDSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for each QoD session." }, "msisdn": { "$ref": "#/components/schemas/Msisdn" }, "source_ip": { "$ref": "#/components/schemas/IpAddress" }, "duration": { "$ref": "#/components/schemas/Duration" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" }, "minItems": 1, "maxItems": 1 } }, "required": [ "id", "msisdn", "source_ip", "duration", "channels" ] }, "Channel": { "type": "object", "description": "Represents a network flow from the mobile device to the specified server(s) and the QoD profile that will be applied to the network.", "properties": { "source": { "$ref": "#/components/schemas/ChannelSourceEndpoint" }, "destination": { "$ref": "#/components/schemas/ChannelDestinationEndpoint" }, "qod_profile": { "$ref": "#/components/schemas/ChannelProfile" }, "projected_end_time": { "$ref": "#/components/schemas/DateTime", "readOnly": true }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/QoDSessionStatusUpdate" }, "readOnly": true } }, "required": [ "source", "destination", "qod_profile" ] }, "ChannelDestinationEndpoint": { "type": "object", "description": "The destination endpoint of the network flow.", "properties": { "cidr": { "$ref": "#/components/schemas/Cidr" }, "port": { "$ref": "#/components/schemas/Port" } }, "required": [ "cidr" ] }, "ChannelProfile": { "type": "string", "description": "The QoD profile configures the flow in the network adapting network characteristics, for example throughput, latency, or jitter." }, "ChannelSourceEndpoint": { "type": "object", "properties": { "port": { "$ref": "#/components/schemas/Port" } }, "description": "The source endpoint of the network flow." }, "QoDSessionRequest": { "type": "object", "properties": { "msisdn": { "$ref": "#/components/schemas/Msisdn" }, "source_ip": { "$ref": "#/components/schemas/IpAddress" }, "duration": { "$ref": "#/components/schemas/Duration" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } }, "required": [ "msisdn", "source_ip", "duration", "channels" ] }, "QoDSessionStatusUpdateCallback": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of the QoD session that has been updated." }, "update": { "$ref": "#/components/schemas/QoDSessionStatusUpdate" }, "projected_end_time": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "update" ] }, "QoDSessionStatusUpdate": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/QoDSessionStatus" }, "updated": { "type": "string", "format": "date-time", "description": "The timestamp of the status update" }, "reason": { "type": "string", "description": "The reason why the status update occurred.", "nullable": true } }, "required": [ "status", "updated" ] }, "QoDSessionStatus": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CANCELLING", "COMPLETED", "FAILED" ], "description": "|- **PENDING.** The QoD session has not yet been processed by the underlying network.\n**ACTIVE.** The QoD session is active, the QoD profile is being applied to the network flow.\n**CANCELLING.** The QoD session is in the process of being cancelled, but has not yet reached a terminal state.\n**COMPLETED.** The QoD session has completed successfully.\n**FAILED.** The QoD session has completed but due to failure, see the reason for more details.", "x-examples": {} }, "ErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "invalid_parameters": { "$ref": "#/components/schemas/ErrorResponseInvalidParameter" } }, "required": [ "title", "detail" ] }, "ErrorUnauthorizedMissingCredentials": { "description": "Missing or Invalid Credentials", "type": "object", "required": [ "type", "title", "details", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors/#unauthorized" }, "title": { "type": "string", "description": "Generic error message", "example": "You did not provide correct credentials." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Check that you're using the correct credentials, and that your account has this feature enabled" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorUnauthorizedInvalidApplication": { "description": "Invalid Application Type", "type": "object", "required": [ "type", "title", "details", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors/#unprovisioned" }, "title": { "type": "string", "description": "Generic error message", "example": "The crendentials provided do not have access to the requested product" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Check your API key is correct and has been whitelisted" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorSessionNotFound": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "description": "Session not found", "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/en/api-errors/#not-found" }, "title": { "type": "string", "description": "Generic error message", "example": "Session not found" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Session does not exist, or you do not have access." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorPaymentRequired": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors/#low-balance" }, "title": { "type": "string", "description": "Generic error message", "example": "Low balance" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "This request could not be performed due to your account balance being low." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorThrottled": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "Rate limit hit" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Please wait, then retry your request" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorInvalidJson": { "description": "Invalid JSON", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors#invalid-json" }, "title": { "type": "string", "description": "Generic error message", "example": "The request body did not contain valid JSON" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorMsisdn": { "description": "Invalid msisdn", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid msisdn" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `msisdn` parameter is invalid." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorDuration": { "description": "Invalid duration", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid duration" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `duration` parameter is invalid." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorChannel": { "description": "Invalid channel", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid channel" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `channel` parameter is invalid." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorResponseInvalidParameter": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } } } }, "parameters": { "session_id": { "name": "session_id", "description": "The unique identifier for the QoD session", "in": "path", "required": true, "schema": { "type": "string" } } } } }