{ "openapi": "3.0.1", "info": { "title": "Twilio - Insights", "description": "Insights Domain V3 API.", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio Support", "url": "https://support.twilio.com", "email": "support@twilio.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0", "x-twilio": { "apiStandards": "v1.0" } }, "servers": [ { "url": "https://insights.twilio.com" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "tags": [ { "name": "TwilioInsights", "description": "Twilio Insights API." } ], "components": { "securitySchemes": { "basic_apikey_or_accountsid": { "scheme": "basic", "type": "http", "description": "This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing." } }, "responses": { "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "BadRequestError": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "UnauthorizedError": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "ForbiddenError": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "RateLimitError": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "headers": { "X-Rate-Limit-Limit": { "schema": { "type": "string" } }, "X-Rate-Limit-Remaining": { "schema": { "type": "string" } }, "X-Rate-Limit-Config": { "schema": { "type": "string" } } }, "schemas": { "PaginationMeta": { "type": "object", "description": "Pagination metadata containing navigation tokens and result information,\nthis schema should according to convention be added to the response\npayload's 'meta' attribute\n", "required": [ "key", "pageSize" ], "properties": { "key": { "type": "string", "nullable": false, "description": "The key of the list property contains the actual data items.\nThis enables programmatic iteration over paginated results.\n", "example": "items" }, "pageSize": { "type": "integer", "nullable": false, "description": "The actual number of items returned in this response.\nMay be less than the requested pageSize for the last page.\n", "example": 20 }, "previousToken": { "type": "string", "nullable": true, "description": "Token to fetch the previous page of results.\nOnly included if there is a previous page, otherwise omitted.\n", "example": "eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0=" }, "nextToken": { "type": "string", "nullable": true, "description": "Token to fetch the next page of results.\nOnly included if there is a next page, otherwise omitted.\n", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } }, "QueryDefinition": { "type": "object", "description": "Structured query definition that specifies what data to retrieve and how to filter, group, and order it", "properties": { "measures": { "type": "array", "description": "Array of measures to retrieve, representing quantitative values or metrics to be calculated", "items": { "type": "string" }, "example": [ "OperatorResult.Count" ] }, "dimensions": { "type": "array", "description": "Array of dimensions to retrieve, representing categorical attributes for grouping and organizing data", "items": { "type": "string" }, "example": [ "DateCreated", "OperatorResults" ] }, "filters": { "type": "array", "description": "Nested filter conditions. Always use `op` and `expressions`.", "items": { "type": "object", "required": [ "expressions" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "AND" }, "expressions": { "type": "array", "items": { "type": "object", "required": [ "op", "field" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "IN" }, "field": { "type": "string", "example": "OperatorResult.Value" }, "values": { "type": "array", "items": { "type": "string" }, "example": [ "positive", "negative" ] } } } } } } }, "orderBy": { "type": "array", "description": "Specifications for sorting the query results by specific fields in ascending or descending order", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Dimension or measure to order by", "example": "OperatorResults.CreatedDate" }, "direction": { "type": "string", "description": "Sort order direction, ascending or descending", "enum": [ "ASC", "DESC" ], "example": "DESC" } } } } } }, "InsightsQueryRequest": { "type": "object", "required": [ "query" ], "properties": { "domain": { "type": "string", "example": "Conversations", "description": "The business domain to execute the query against" }, "query": { "$ref": "#/components/schemas/QueryDefinition" } } }, "InsightsQueryResponse": { "type": "object", "properties": { "domain": { "type": "string", "example": "Insights", "description": "Indicates the business domain the query was executed against" }, "items": { "type": "array", "description": "Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions.", "items": { "type": "object", "description": "Query result object with dynamic properties based on requested measures and dimensions.", "additionalProperties": { "description": "Dynamic property values based on requested measures and dimensions." } }, "example": [ { "Id": "conv1", "Languages": [ "en" ], "Channels": [ "voice" ], "OperatorResult.Value": "positive" }, { "Id": "conv2", "Languages": [ "en", "es" ], "Channels": [ "chat" ], "OperatorResult.Value": "negative" } ] }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "InsightsMetadataResponse": { "type": "object", "description": "Response containing metadata about available cubes, measures, and dimensions for a domain", "properties": { "domain": { "type": "string", "example": "Insights", "description": "The business domain name for which metadata is being provided" }, "cubes": { "type": "array", "description": "List of data cubes available in the domain, each containing measures and dimensions", "items": { "type": "object", "required": [ "name", "measures", "dimensions" ], "properties": { "name": { "type": "string", "description": "Name of the cube, used as a reference in queries" }, "description": { "type": "string", "description": "Human-readable description of what the cube represents" }, "measures": { "type": "array", "description": "List of measures available in the cube, representing quantitative values that can be aggregated", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this measure in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this measure represents" }, "type": { "type": "string", "description": "Type of the measure" }, "aggregation": { "type": "string", "description": "Aggregation type for the measure (e.g., sum, count, average)" } } } }, "dimensions": { "type": "array", "description": "List of dimensions available in the cube, representing categorical attributes for grouping data", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this dimension in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this dimension represents" }, "type": { "type": "string", "description": "Data type of the dimension (e.g., string, number, boolean, date)" } } } } } } } } } } }, "paths": { "/v3/InsightsDomains/Conversations/Query": { "servers": [ { "url": "https://insights.twilio.com" } ], "post": { "summary": "Execute a semantic query", "description": "Execute a semantic query against the Conversations domain.", "tags": [ "TwilioInsights" ], "operationId": "CreateQueryResults", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 20, "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryRequest" } } } }, "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "get": { "summary": "Fetch semantic query results", "tags": [ "TwilioInsights" ], "operationId": "FetchQueryResults", "parameters": [ { "name": "pageToken", "in": "query", "description": "Pagination token", "required": true, "schema": { "type": "string", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } ], "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/Metadata": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Fetch Metadata for the Conversations domain", "description": "Fetch Metadata for the Conversations domain.", "tags": [ "TwilioInsights" ], "operationId": "FetchMetadata", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsMetadataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } } } }