{ "openapi": "3.0.0", "info": { "version": "1.0.1", "title": "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": "The [Traffic Control API](/messaging/traffic-control/overview#traffic-control-api) is a RESTful API that provides access to real-time and historical queue size data for the Vonage Traffic Control service. The API allows you to retrieve the current queue size for a specific product, as well as historical queue size data for a specific product over a specified date range.", "x-labe": "beta", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" } }, "servers": [ { "url": "https://api.nexmo.com" } ], "security": [ { "basicAuth": [] } ], "paths": { "/v0.1/vtc/queues/product/{product_name}/current": { "get": { "operationId": "getCurrentQueueSizeInfo", "summary": "Retrieve the current queue size", "parameters": [ { "name": "product_name", "in": "path", "description": "The name of the product to retrieve the queue size for. Must be `sms`.", "required": true, "schema": { "type": "string", "enum": [ "sms" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "required": [ "_embedded", "_links" ], "type": "object", "properties": { "_embedded": { "type": "object", "readOnly": true, "properties": { "data": { "type": "object", "readOnly": true, "properties": { "queue_size": { "type": "integer", "readOnly": true, "example": 100 } } } } }, "_links": { "required": [ "self" ], "type": "object", "properties": { "self": { "required": [ "href", "templated" ], "type": "object", "properties": { "href": { "type": "string", "format": "URL", "example": "/v0.1/vtc/queues/product/sms/current" }, "templated": { "type": "boolean", "example": false } } } } } } } } } }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/responses/ErrorInvalidProduct" } } } }, "429": { "$ref": "#/components/responses/ErrorThrottled" }, "500": { "$ref": "#/components/responses/ErrorInternal" } } } }, "/v0.1/vtc/queues/product/{product_name}/historical": { "get": { "operationId": "getHistoricalQueueSizeInfo", "summary": "Retrieve historical queue size data", "parameters": [ { "name": "product_name", "in": "path", "description": "The name of the product to retrieve the queue size for. Must be `sms`.", "required": true, "schema": { "type": "string", "enum": [ "sms" ] } }, { "name": "start_date", "in": "query", "description": "The date at which the returned dataset should start in ISO8601 format.", "required": true, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "The date at which the returned dataset should end in ISO8601 format.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "required": [ "_embedded", "_links" ], "type": "object", "properties": { "_embedded": { "type": "object", "readOnly": true, "properties": { "historical_data": { "type": "array", "items": { "type": "object", "properties": { "queue_size": { "type": "integer", "example": 30 }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-06-12T15:59:22.870Z" } } } } } }, "_links": { "required": [ "self" ], "type": "object", "properties": { "self": { "required": [ "href", "templated" ], "type": "object", "properties": { "href": { "type": "string", "format": "URL", "example": "/v0.1/vtc/queues/product/sms/historical?start_date=2024-06-12T15:59:22.870Z&end_date=2024-06-12T15:59:42.870Z" }, "templated": { "type": "boolean", "example": false } } } } } } } } } }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/ErrorThrottled" }, "500": { "$ref": "#/components/responses/ErrorInternal" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "responses": { "AuthorizationError": { "description": "Authentication failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/responses/ErrorUnauthorizedMissingCredentials" }, { "$ref": "#/components/responses/ErrorUnauthorizedUnprovisioned" } ] } } } }, "UnprocessableEntityError": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/responses/ErrorInvalidProduct" }, { "$ref": "#/components/responses/ErrorInvalidDateRange" }, { "$ref": "#/components/responses/ErrorInvalidDateFormat" }, { "$ref": "#/components/responses/ErrorMissingStartDate" }, { "$ref": "#/components/responses/ErrorMissingEndDate" } ] } } } }, "ErrorThrottled": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/en/api-errors/traffic-control#throttled" }, "title": { "type": "string", "description": "Generic error message", "example": "Request Throttled" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Your request rate exceeds the allowed limit for this account." } } } } } }, "ErrorInternal": { "description": "Internal error", "content": { "application/json": { "schema": { "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/traffic-control#internal-error" }, "title": { "type": "string", "description": "Generic error message", "example": "Internal error occurred." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "An internal error occurred. Please try again later." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "7ca3a30c-aa13-47fa-b087-85e1a91a911a" } } } } } }, "ErrorUnauthorizedMissingCredentials": { "description": "Missing or Invalid Credentials", "type": "object", "required": [ "type", "title", "details" ], "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" } } }, "ErrorUnauthorizedUnprovisioned": { "description": "Invalid Application Type", "type": "object", "required": [ "type", "title", "details" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.nexmo.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" } } }, "ErrorInvalidProduct": { "description": "Invalid Product Parameter", "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/traffic-control#invalid-product" }, "title": { "type": "string", "description": "Generic error message", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Given product is not supported" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "3e17232a-9aca-4d8a-9f4b-934de52f6826" } } }, "ErrorInvalidDateRange": { "description": "Invalid Date Range", "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/traffic-control#invalid-product" }, "title": { "type": "string", "description": "Generic error message", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `start_date` must be before the `end_date`." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "5dc3db84-ee7a-49f5-b3fe-f21fbd08bf6a" } } }, "ErrorInvalidDateFormat": { "description": "Invalid Date Format", "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/traffic-control#invalid-date-format" }, "title": { "type": "string", "description": "Generic error message", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Invalid date format. Please provide the `start_date` and `end_date` in ISO8601 format." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "8c0a7791-43ec-42be-871c-b14975ac5bb6" } } }, "ErrorMissingStartDate": { "description": "Missing Start Date", "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/traffic-control#missing-query-param" }, "title": { "type": "string", "description": "Generic error message", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Required QueryValue `start_date` not specified." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "343749d2-95bf-4d19-9a87-e4ecd2f218c8" } } }, "ErrorMissingEndDate": { "description": "Missing End Date", "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/traffic-control#missing-query-param" }, "title": { "type": "string", "description": "Generic error message", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Required QueryValue `end_date` not specified." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "343749d2-95bf-4d19-9a87-e4ecd2f218c8" } } }, "GenericJsonHalResponse": { "required": [ "_embedded", "_links" ], "type": "object", "properties": { "_embedded": { "type": "object", "additionalProperties": true }, "_links": { "$ref": "#/components/responses/Links" } } }, "Link": { "required": [ "href", "templated" ], "type": "object", "properties": { "href": { "type": "string" }, "templated": { "type": "boolean" } } }, "Links": { "required": [ "first", "last", "next", "prev", "self" ], "type": "object", "properties": { "self": { "$ref": "#/components/responses/Link" }, "first": { "$ref": "#/components/responses/Link" }, "prev": { "$ref": "#/components/responses/Link" }, "next": { "$ref": "#/components/responses/Link" }, "last": { "$ref": "#/components/responses/Link" } } } } }, "x-errors": { "throttled": { "description": "Your request rate exceeds the allowed limit for this account." }, "internal-error": { "description": "An internal error occurred. Please try again later." }, "invalid-product": { "description": "Path parameter `product_name` didn't validate. The given product is not supported." }, "invalid-provisioner-command": { "description": "The path segment denoting the action to be performed is not valid. The only allowed actions are `/activate` and `/deactivate`." }, "invalid-date-format": { "description": "Invalid date format. Please provide the `start_date` and `end_date` in ISO8601 format." }, "missing-query-param": { "description": "One or more required query parameters was not specified." } } }