{ "openapi": "3.0.3", "info": { "termsOfService": "https://www.vonage.com/legal/communications-apis/terms-of-use/", "contact": { "name": "Vonage Developer Relations", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0", "title": "Vonage Traffic Control API", "x-metaTitle": "Vonage Traffic Control API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Traffic Control API in this reference guide. Learn more in Vonage's API documentation.", "description": "API for activating or deactivating the Vonage Traffic Control (VTC) service for supported products and for checking the current VTC status. For more infomation, see our [developer documentation](https://developer.vonage.com)" }, "servers": [ { "url": "https://api.nexmo.com/vtc/v1", "description": "API Server" } ], "tags": [ { "name": "Traffic Control" } ], "paths": { "/configuration/product/{product_name}": { "get": { "tags": [ "Traffic Control" ], "security": [ { "basicAuth": [] } ], "summary": "Get VTC activation status for the product", "description": "Returns the current activation status of the Vonage Traffic Control (VTC) service for the specified product.\n", "operationId": "getVTCActivation", "parameters": [ { "$ref": "#/components/parameters/ProductNameParameter" } ], "responses": { "200": { "$ref": "#/components/responses/VtcStatusResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/configuration/product/{product_name}/activate": { "post": { "tags": [ "Traffic Control" ], "security": [ { "basicAuth": [] } ], "summary": "Activate VTC for the product", "description": "Activates the Vonage Traffic Control (VTC) service for the specified product.\n", "operationId": "activateVTCForProduct", "parameters": [ { "$ref": "#/components/parameters/ProductNameParameter" } ], "responses": { "202": { "$ref": "#/components/responses/VtcActivateResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/configuration/product/{product_name}/deactivate": { "post": { "tags": [ "Traffic Control" ], "security": [ { "basicAuth": [] } ], "summary": "Deactivate VTC for the product", "description": "Deactivates the Vonage Traffic Control (VTC) service for the specified product.\n", "operationId": "deactivateVTCForProduct", "parameters": [ { "$ref": "#/components/parameters/ProductNameParameter" } ], "responses": { "202": { "$ref": "#/components/responses/VtcDeactivateResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/queues/product/{product_name}/current": { "get": { "tags": [ "Traffic Control" ], "security": [ { "basicAuth": [] } ], "summary": "Retrieve the current queue size", "description": "Retrieves the current queue size for the Vonage Traffic Control (VTC) service for the specified product.\n", "operationId": "getCurrentQueueSizeInfo", "parameters": [ { "$ref": "#/components/parameters/ProductNameParameter" } ], "responses": { "200": { "$ref": "#/components/responses/CurrentQueueSizeResponse" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/queues/product/{product_name}/historical": { "get": { "tags": [ "Traffic Control" ], "security": [ { "basicAuth": [] } ], "summary": "Retrieve historical queue size data", "description": "Retrieves historical queue size data for the Vonage Traffic Control (VTC) service for the specified product over a specified date range.\n", "operationId": "getHistoricalQueueSizeInfo", "parameters": [ { "$ref": "#/components/parameters/ProductNameParameter" }, { "$ref": "#/components/parameters/StartDateParameter" }, { "$ref": "#/components/parameters/EndDateParameter" } ], "responses": { "200": { "$ref": "#/components/responses/HistoricalQueueSizeResponse" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "parameters": { "ProductNameParameter": { "name": "product_name", "in": "path", "required": true, "description": "The product name for which the VTC service is being managed. Only supported products are allowed.\n", "schema": { "type": "string", "enum": [ "sms" ] } }, "StartDateParameter": { "name": "start_date", "in": "query", "required": true, "description": "The date at which the returned dataset should start in ISO8601 format.", "schema": { "type": "string", "format": "date-time", "example": "2024-06-12T15:59:22.870Z" } }, "EndDateParameter": { "name": "end_date", "in": "query", "required": true, "description": "The date at which the returned dataset should end in ISO8601 format.", "schema": { "type": "string", "format": "date-time", "example": "2024-06-12T15:59:42.870Z" } } }, "schemas": { "VtcStatus": { "type": "object", "description": "Object representing the activated/deactivated status of the Vonage Traffic Control (VTC) service.\n", "properties": { "status": { "type": "string", "description": "Indicates whether the VTC service is activated (`ACTIVATED`) or deactivated (`DEACTIVATED`) for the product.\n", "enum": [ "ACTIVATED", "DEACTIVATED" ], "example": "ACTIVATED" } }, "required": [ "status" ] }, "QueueSize": { "type": "object", "description": "Object representing the current queue size for the VTC service.\n", "properties": { "queue_size": { "type": "integer", "description": "The current number of messages in the queue.", "example": 100, "readOnly": true } }, "required": [ "queue_size" ] }, "CurrentQueueSizeHalResponse": { "type": "object", "description": "Represents a HAL-formatted response containing the current queue size and relevant links.\n", "required": [ "_embedded", "_links" ], "properties": { "_embedded": { "type": "object", "readOnly": true, "properties": { "data": { "$ref": "#/components/schemas/QueueSize" } } }, "_links": { "$ref": "#/components/schemas/_links" } } }, "HistoricalQueueData": { "type": "object", "description": "Object representing a historical queue size data point.\n", "properties": { "queue_size": { "type": "integer", "description": "The queue size at a specific point in time.", "example": 30 }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of when the queue size was recorded.", "example": "2024-06-12T15:59:22.870Z" } }, "required": [ "queue_size", "timestamp" ] }, "HistoricalQueueSizeHalResponse": { "type": "object", "description": "Represents a HAL-formatted response containing historical queue size data and relevant links.\n", "required": [ "_embedded", "_links" ], "properties": { "_embedded": { "type": "object", "readOnly": true, "properties": { "historical_data": { "type": "array", "description": "Array of historical queue size data points.", "items": { "$ref": "#/components/schemas/HistoricalQueueData" } } } }, "_links": { "$ref": "#/components/schemas/_links" } } }, "VtcStatusHalResponse": { "type": "object", "description": "Represents a HAL-formatted response containing the VTC status and relevant links.\nStatus is only returned on synchronous operations.\n", "required": [ "_embedded", "_links" ], "properties": { "_embedded": { "type": "object", "readOnly": true, "properties": { "data": { "$ref": "#/components/schemas/VtcStatus" } } }, "_links": { "$ref": "#/components/schemas/_links" } } }, "HalLink": { "type": "object", "description": "A single HAL link object", "required": [ "href" ], "properties": { "href": { "type": "string", "description": "The URL for the resource", "example": "https://api.vonage.com/v1/resources/abc123" }, "templated": { "type": "boolean", "description": "Indicates if the href is a URI template", "example": false }, "type": { "type": "string", "description": "Media type hint for the target resource", "example": "application/json" }, "name": { "type": "string", "description": "Secondary key for selecting link objects", "example": "resource-name" }, "title": { "type": "string", "description": "Human-readable title for the link", "example": "Resource Title" } } }, "SelfLink": { "type": "object", "description": "Link to the current resource (always required in HAL)", "required": [ "self" ], "properties": { "self": { "$ref": "#/components/schemas/HalLink" } } }, "_links": { "type": "object", "description": "HAL Links object", "allOf": [ { "$ref": "#/components/schemas/SelfLink" } ] }, "ErrorResponse": { "type": "object", "description": "Base error response following RFC 7807", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "An error occurred" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "More details about what went wrong" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorResponseWithInvalidParameters": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "required": [ "detail" ], "properties": { "invalid_parameters": { "type": "array", "description": "List of invalid parameters", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "Name of the invalid parameter", "example": "name" }, "reason": { "type": "string", "description": "Reason why the parameter is invalid", "example": "Must not be empty" } } } } } } ] } }, "responses": { "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponseWithInvalidParameters" } } } }, "401": { "description": "Authentication failure", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "oneOf": [ { "description": "Missing or Invalid Credentials", "type": "object", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/#unathorized" }, "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" } } }, { "description": "Invalid Application Type", "type": "object", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/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" } } } ] } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponseWithInvalidParameters" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "CurrentQueueSizeResponse": { "description": "The current queue size for the specified product.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentQueueSizeHalResponse" }, "examples": { "currentQueueSize": { "value": { "_embedded": { "data": { "queue_size": 100 } }, "_links": { "self": { "href": "/v1/vtc/queues/product/sms/current", "templated": false } } } } } } } }, "HistoricalQueueSizeResponse": { "description": "Historical queue size data for the specified product over a specified date range.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalQueueSizeHalResponse" }, "examples": { "historicalQueueSize": { "value": { "_embedded": { "historical_data": [ { "queue_size": 30, "timestamp": "2024-06-12T15:59:22.870Z" }, { "queue_size": 45, "timestamp": "2024-06-12T16:00:22.870Z" }, { "queue_size": 50, "timestamp": "2024-06-12T16:01:22.870Z" } ] }, "_links": { "self": { "href": "/v1/vtc/queues/product/sms/historical?start_date=2024-06-12T15:59:22.870Z&end_date=2024-06-12T16:01:22.870Z", "templated": false } } } } } } } }, "VtcStatusResponse": { "description": "The current VTC activation status for the specified product.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VtcStatusHalResponse" }, "examples": { "activated": { "value": { "_embedded": { "data": { "status": "ACTIVATED" } }, "_links": { "self": { "href": "/v1/vtc/configuration/product/sms", "templated": false }, "activate": { "href": "/v1/vtc/configuration/product/sms/activate", "templated": false }, "deactivate": { "href": "/v1/vtc/configuration/product/sms/deactivate", "templated": false } } } }, "deactivated": { "value": { "_embedded": { "data": { "status": "DEACTIVATED" } }, "_links": { "self": { "href": "/v1/vtc/configuration/product/sms", "templated": false }, "activate": { "href": "/v1/vtc/configuration/product/sms/activate", "templated": false }, "deactivate": { "href": "/v1/vtc/configuration/product/sms/deactivate", "templated": false } } } } } } } }, "VtcActivateResponse": { "description": "A HAL response with a relative link to check the resource status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VtcStatusHalResponse" }, "examples": { "activated": { "value": { "_embedded": {}, "_links": { "self": { "href": "/v1/vtc/configuration/product/sms", "templated": false }, "activate": { "href": "/v1/vtc/configuration/product/sms/activate", "templated": false }, "deactivate": { "href": "/v1/vtc/configuration/product/sms/deactivate", "templated": false } } } } } } } }, "VtcDeactivateResponse": { "description": "A HAL response with a relative link to check the resource status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VtcStatusHalResponse" }, "examples": { "deactivated": { "value": { "_embedded": {}, "_links": { "self": { "href": "/v1/vtc/configuration/product/sms", "templated": false }, "activate": { "href": "/v1/vtc/configuration/product/sms/activate", "templated": false }, "deactivate": { "href": "/v1/vtc/configuration/product/sms/deactivate", "templated": false } } } } } } } } }, "headers": { "X-Request-Id": { "description": "A unique identifier for the request, used for tracking and debugging", "schema": { "type": "string", "format": "uuid", "example": "f94b4e56-604e-07e5-e5ad-5a7228618f81" } }, "X-RateLimit-Limit": { "description": "Request limit per hour", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Remaining requests", "schema": { "type": "integer", "example": 5 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when limit resets", "schema": { "type": "integer", "example": 1769182705723 } }, "Retry-After": { "description": "Seconds until next request allowed", "schema": { "type": "integer", "example": 15 } } } }, "x-errors": null }