--- updatedAt: 2026-03-01T18:55:05.000Z agentTools: siteIndex: https://techdocs.akamai.com/llms.txt projectIndex: https://techdocs.akamai.com/alerts-app/llms.txt --- # Create a new alert Creates a new alert definition based on a template. The template's required `fields` represent criteria you may use to trigger an alert, but the new definition's `fields` specify the set of values that actually trigger the alert. After you create a new alert, it may take a couple of minutes before it has enough information before it can fire. # OpenAPI definition ```json { "externalDocs": { "description": "See documentation for Akamai's Alerts API", "url": "https://techdocs.akamai.com/alerts-app/reference" }, "info": { "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Alert definitions", "version": "v1" }, "openapi": "3.0.0", "paths": { "/alert-definitions": { "post": { "description": "Creates a new alert definition based on a template. The template's required `fields` represent criteria you may use to trigger an alert, but the new definition's `fields` specify the set of values that actually trigger the alert. After you create a new alert, it may take a couple of minutes before it has enough information before it can fire.", "externalDocs": { "description": "See documentation for this operation in Akamai's Alerts API", "url": "https://techdocs.akamai.com/alerts-app/reference/post-definition" }, "operationId": "post-definition", "parameters": [ { "description": "For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).", "in": "query", "name": "accountSwitchKey", "required": false, "schema": { "example": "1-5C0YLB:1-8BYUX", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "fields": { "aca_cpcode": [ "111", "33190" ], "alertLowerBound": 5, "definitionId": "", "email": [ "nomail@akamai.com" ], "emailBrief": [ "12345678@akamai.com" ], "emailHtmlFormat": true, "group": [ "grp_123456" ], "isSum": true, "name": "myTestAlertName", "network": "myNetwork", "param": 20, "paramName": "cpercent", "templateId": "s@150" }, "origin": "STATIC" }, "schema": { "additionalProperties": false, "description": "Alert configured with thresholds for monitoring.", "properties": { "definitionId": { "description": "Identifies each alert definition.", "minLength": 1, "type": "string" }, "fields": { "additionalProperties": false, "description": "A mapping of contextual fields relevant to the alert.", "properties": { "email": { "description": "Email addresses of alert notification's recipients.", "items": { "minLength": 1, "type": "string" }, "minItems": 0, "type": "array" }, "group": { "description": "Group identifiers to which alert should be assigned.", "items": { "minimum": 1, "type": "integer" }, "minItems": 1, "type": "array" }, "name": { "description": "The human readable name for the alert.", "minLength": 1, "type": "string" }, "templateId": { "description": "Identifies the template.", "minLength": 1, "type": "string" } }, "required": [ "templateId", "name" ], "type": "object", "x-akamai": { "file-path": "schemas/fields-map.yaml" } }, "origin": { "description": "Identifies the type of alert the template enables, either `STATIC` or `ADAPTIVE`. Static alert types specify raw values, while the adaptive alert type expresses standard deviations. The only available ADAPTIVE alert identifies excessive traffic, and its `templateId` is `a@1`.", "enum": [ "STATIC", "ADAPTIVE" ], "type": "string" } }, "required": [ "fields" ], "type": "object", "x-akamai": { "file-path": "schemas/post-definition.yaml" } } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "accountId": "A-CCT5678", "alertEnvironment": "COMMERCIAL", "definitionId": "s@123", "editInfo": { "active": true, "createdAt": "2006-02-16T20:49:54Z", "createdBy": "hgildong", "editAt": "2006-02-16T20:49:54Z", "editBy": "szhang" }, "fields": { "aca_cpcode": [ "111", "33190" ], "alertLowerBound": 5, "definitionId": "s@123", "email": [ "nomail@akamai.com" ], "emailBrief": [ "12345678@akamai.com" ], "emailHtmlFormat": true, "isSum": true, "name": "myTestAlertName", "network": "myNetwork", "param": 20, "paramName": "cpercent", "templateId": "s@150" }, "origin": "STATIC" }, "schema": { "additionalProperties": false, "description": "Alert configured with thresholds for monitoring.", "properties": { "accountId": { "description": "Identifies the account under which the alert was created.", "minLength": 1, "type": "string" }, "alertEnvironment": { "description": "__Read-only__ Identifies the type of environment in which the alert was created, either `GOVCLOUD` for alerts operating in governmental environments, or `COMMERCIAL` for all other alerts. ", "enum": [ "COMMERCIAL", "GOVCLOUD" ], "readOnly": true, "type": "string" }, "definitionId": { "description": "Identifies the alert definition.", "minLength": 1, "type": "string" }, "editInfo": { "additionalProperties": false, "description": "A summary of the alert's creation time and most recent edit.", "properties": { "active": { "description": "When the alert `origin` is `STATIC`, indicates if the alert is allowed to fire. A `false` value may be due to variations in account and contract status that leaves the alert configured but inactive.", "type": "boolean" }, "createdAt": { "description": "ISO 8601 timestamp for when the alert was created.", "format": "date-time", "type": "string" }, "createdBy": { "description": "The user who created the alert.", "minLength": 1, "type": "string" }, "editAt": { "description": "ISO 8601 timestamp for when the alert was last edited.", "format": "date-time", "type": "string" }, "editBy": { "description": "The user who last edited the alert.", "minLength": 1, "type": "string" } }, "required": [ "createdAt", "createdBy", "editAt", "editBy", "active" ], "type": "object" }, "fields": { "additionalProperties": false, "description": "The set of criteria that determines when the alert fires. The object's members vary depending on the template on which the alert is based. However, all `fields` include a `name`, the `templateId` on which the alert was based, and an array of `email` addresses for the alert's recipients.", "properties": { "email": { "description": "Email addresses of alert notification's recipients.", "items": { "minLength": 1, "type": "string" }, "minItems": 0, "type": "array" }, "group": { "description": "Group identifiers to which alert should be assigned.", "items": { "minimum": 1, "type": "integer" }, "minItems": 1, "type": "array" }, "name": { "description": "The human readable name for the alert.", "minLength": 1, "type": "string" }, "templateId": { "description": "Identifies the template.", "minLength": 1, "type": "string" } }, "required": [ "templateId", "name" ], "type": "object", "x-akamai": { "file-path": "schemas/fields-map.yaml" } }, "links": { "description": "Link relations to schemas and REST endpoints.", "items": { "additionalProperties": false, "properties": { "href": { "description": "Link to resource of type described by rel.", "minLength": 1, "type": "string" }, "rel": { "description": "Describes type of link.", "minLength": 1, "type": "string" } }, "required": [ "rel", "href" ], "type": "object" }, "minItems": 2, "type": "array", "uniqueItems": true, "x-akamai": { "file-path": "schemas/links.yaml" } }, "origin": { "description": "Identifies the type of alert the template enables, either `STATIC` or `ADAPTIVE`. Static alert types specify raw values, while the adaptive alert type expresses standard deviations. The only available `ADAPTIVE` alert identifies excessive traffic, and its `templateId` is `a@1`.", "enum": [ "STATIC", "ADAPTIVE" ], "type": "string" } }, "required": [ "fields" ], "type": "object", "x-akamai": { "file-path": "schemas/definition.yaml" } } } }, "description": "The response provides the newly created alert." }, "400": { "content": { "application/problem+json": { "example": { "detail": "Not a valid alert Id", "status": 400, "title": "Illegal Argument", "type": "/alerts-api/error-types/ILLEGAL_ARGUMENT" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Bad request](https://techdocs.akamai.com/alerts-app/reference/400).", "x-akamai": { "file-path": "errors/400.yaml" } }, "401": { "content": { "application/problem+json": { "example": { "clientIp": "192.0.2.0", "detail": "The signature does not match", "instance": "https://akab-xxxxx-xxxxx.luna.akamaiapis.net/alerts/v2/alert-definitions", "method": "GET", "requestId": "933ed8a4", "requestTime": "2023-07-06T08:11:36Z", "serverIp": "192.0.2.48", "status": 401, "title": "Not authorized", "type": "https://problems.luna.akamaiapis.net/-/pep-authn/deny" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Unauthorized error](https://techdocs.akamai.com/alerts-app/reference/401).", "x-akamai": { "file-path": "errors/401.yaml" } }, "403": { "content": { "application/problem+json": { "example": { "detail": "User lacks scope on account", "status": 403, "title": "Authorization Error", "type": "/alerts-api/error-types/AUTHZ_PROBLEM" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Access is forbidden](https://techdocs.akamai.com/alerts-app/reference/403).", "x-akamai": { "file-path": "errors/403.yaml" } }, "405": { "content": { "application/problem+json": { "example": { "detail": "Request method 'POST' not supported", "status": 405, "title": "Method Not Allowed", "type": "/alerts-api/error-types/METHOD_NOT_ALLOWED" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Method not allowed](https://techdocs.akamai.com/alerts-app/reference/405).", "x-akamai": { "file-path": "errors/405.yaml" } }, "415": { "content": { "application/problem+json": { "example": { "detail": "Content type 'application/xml' not supported", "status": 415, "title": "Unsupported Media Type", "type": "/alerts-api/error-types/UNSUPPORTED_MEDIA_TYPE" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Unsupported media type](https://techdocs.akamai.com/alerts-app/reference/415).", "x-akamai": { "file-path": "errors/415.yaml" } }, "500": { "content": { "application/problem+json": { "example": { "detail": "Operation can't completed with invalid alertDefinitionId : a@123", "status": 500, "title": "Internal Server Error", "type": "/alerts-api/error-types/INTERNAL_SERVER_ERROR" }, "schema": { "additionalProperties": true, "description": "Specifies the errors.", "properties": { "clientIp": { "description": "IP address of the client that requested the `instance` URL.", "minLength": 1, "type": "string" }, "code": { "description": "The error code that distinguishes each `type`.", "minLength": 1, "type": "string" }, "detail": { "description": "More information about the error.", "minLength": 1, "type": "string" }, "instance": { "description": "The URL you called that produced the error.", "minLength": 1, "type": "string" }, "method": { "description": "The HTTP method you called on the `instance` URL.", "minLength": 1, "type": "string" }, "requestId": { "description": "Identifies each separate request.", "minLength": 1, "type": "string" }, "requestTime": { "description": "ISO 8601 timestamp marking when the request occurred.", "format": "date-time", "type": "string" }, "serverIp": { "description": "IP address of the server.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP status code.", "minimum": 1, "type": "integer" }, "title": { "description": "Title of the error.", "minLength": 1, "type": "string" }, "type": { "description": "Type of error, represented as a non-navigable URI.", "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "detail" ], "type": "object", "x-akamai": { "file-path": "schemas/problem.yaml" } } } }, "description": "[Server error](https://techdocs.akamai.com/alerts-app/reference/500).", "x-akamai": { "file-path": "errors/500.yaml" } } }, "summary": "Create a new alert", "tags": [ "Alert definitions" ] }, "x-akamai": { "file-path": "paths/alert-definitions.yaml", "path-info": "/alert-definitions" } } }, "servers": [ { "url": "https://{hostname}/alerts/v2" } ], "x-akamai": { "auth-type": "EDGE_GRID", "file-path": "04-alert-definitions.yaml" }, "x-readme": { "samples-languages": [ "curl", "python", "node" ], "explorer-enabled": true, "proxy-enabled": true } } ``` # Sibling pages * [List alerts](https://techdocs.akamai.com/alerts-app/reference/get-definitions.md) * [Get an alert](https://techdocs.akamai.com/alerts-app/reference/get-definition.md) * [Update an alert](https://techdocs.akamai.com/alerts-app/reference/put-definition.md) * [Remove an alert](https://techdocs.akamai.com/alerts-app/reference/delete-definition.md) * [List adaptive alert activity log](https://techdocs.akamai.com/alerts-app/reference/get-definition-alert-activities.md)