Akamai Behavioral DDoS profiles API

openapi: 3.0.0
info:
  title: 'Akamai: API Endpoint Definition Access tokens Behavioral DDoS profiles API'
  version: '2'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{hostname}/api-definitions/v2
tags:
- name: Behavioral DDoS profiles
paths:
  /configs/{configId}/versions/{versionNumber}/behavioral-ddos:
    parameters:
    - description: A unique identifier for each configuration.
      in: path
      name: configId
      required: true
      schema:
        example: 77653
        format: int64
        type: integer
      x-akamai:
        file-path: parameters/config-id-path.yaml
    - description: A unique identifier for each version of a configuration.
      in: path
      name: versionNumber
      required: true
      schema:
        example: 25
        type: integer
      x-akamai:
        file-path: parameters/version-number-path.yaml
    x-akamai:
      file-path: paths/behavioral-ddos-profiles.yaml
      path-info: /configs/{configId}/versions/{versionNumber}/behavioral-ddos
    post:
      description: Creates a new Behavioral DDoS profile for a specific configuration version. _Products:_ All.
      externalDocs:
        description: See documentation for this operation in Akamai's Application Security API
        url: https://techdocs.akamai.com/application-security/reference/post-behavioral-ddos-profile
      operationId: post-behavioral-ddos-profile
      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:
              bypassCondition:
                atomicConditions:
                - checkIps: connecting
                  className: NetworkListCondition
                  positiveMatch: true
                  value:
                  - 100065_IPLIST
                - className: RequestHeaderCondition
                  name:
                  - Content-Type
                  nameWildcard: true
                  positiveMatch: true
                  value:
                  - application/json
                  valueCase: false
                  valueWildcard: true
              configId: 1
              configVersion: 1
              description: This is a description of the profile
              exceptions:
              - hosts:
                - secure.host1.com
                - help.host3.com
                paths:
                - /path1
                - /path2
                - /path3
              hostnames:
              - secure.host1.com
              - www.host2.com
              - help.host3.com
              - info.host4.com
              name: My first BDE profile
              sensitivity: STRICT
              sensitivityOverrides:
              - host: info.host4.com
                path: /path3
                sensitivity: MODERATE
              suspend:
                fromDate: '2025-02-20T14:00:00Z'
                hostnames:
                - secure.host1.com
                toDate: '2025-03-20T14:00:00Z'
            schema:
              additionalProperties: false
              description: Contains details about a Behavioral DDoS profile.
              properties:
                bypassCondition:
                  additionalProperties: false
                  description: Exempts specific clients from being processed by the Behavioral DDoS profile.
                  properties:
                    atomicConditions:
                      description: Specify one or more types of conditions to match on. You can match on client lists, request headers, or both.
                      items:
                        oneOf:
                        - additionalProperties: false
                          description: Collects data needed for condition matches on request headers.
                          properties:
                            className:
                              description: Choose `RequestHeaderCondition` to match a header from the requesting client to the specified header.
                              enum:
                              - RequestHeaderCondition
                              type: string
                            name:
                              description: Use `name` to check whether the specified header exists.
                              items:
                                minLength: 1
                                type: string
                              minItems: 1
                              type: array
                              uniqueItems: true
                            nameWildcard:
                              description: Whether to interpret `?` and `*` as wildcards in the specified `name`.
                              type: boolean
                            positiveMatch:
                              description: __Read-only__ Whether the condition triggers on a match or lack of match.
                              readOnly: true
                              type: boolean
                            value:
                              description: Unique header values. Use both `value` and `name` to check whether the requesting client’s header matches the specified headers.
                              items:
                                minLength: 1
                                type: string
                              minItems: 0
                              nullable: true
                              type: array
                              uniqueItems: true
                            valueCase:
                              description: Whether to consider case when matching header values, `true` for case-sensitive matches.
                              type: boolean
                            valueWildcard:
                              description: Whether to interpret `?` and `*` as wildcards in the specified `value`.
                              type: boolean
                          required:
                          - className
                          - name
                          title: RequestHeaderCondition
                          type: object
                          x-akamai:
                            file-path: schemas/behavioral-ddos-bypass-request-header-condition.yaml
                        - additionalProperties: false
                          description: Collects data needed for condition matches on client lists and network lists.
                          properties:
                            checkIps:
                              description: __Read-only__ Whether the connecting IP or both the connecting IP and `X-Forwarded-For` (XFF) header match on the client list or network list. Behavioral DDoS bypass supports `connecting` only.
                              enum:
                              - connecting
                              readOnly: true
                              type: string
                            className:
                              description: Choose `NetworkListCondition` to match the requesting client's identifier, like IP, GEO, ASN or TLS fingerprint, against the specified client or network list. The only currently supported syntax is `NetworkListCondition`.
                              enum:
                              - NetworkListCondition
                              type: string
                            positiveMatch:
                              description: __Read-only__ Whether the condition triggers on a match or lack of match.
                              readOnly: true
                              type: boolean
                            value:
                              description: Identifies the client list or network list.
                              items:
                                minLength: 1
                                type: string
                              minItems: 0
                              nullable: true
                              type: array
                              uniqueItems: true
                          required:
                          - className
                          - value
                          title: NetworkListCondition
                          type: object
                          x-akamai:
                            file-path: schemas/behavioral-ddos-bypass-client-list-condition.yaml
                      minItems: 1
                      type: array
                  type: object
                configId:
                  description: Uniquely identifies the security configuration.
                  format: int64
                  type: integer
                configVersion:
                  description: The security configuration version.
                  type: integer
                createDate:
                  description: __Read-only__ The ISO 8601 timestamp when you created the Behavioral DDoS profile.
                  format: date-time
                  readOnly: true
                  type: string
                createdBy:
                  description: __Read-only__ The username of the person who created the Behavioral DDoS profile.
                  readOnly: true
                  type: string
                description:
                  description: A description of the profile.
                  type: string
                exceptions:
                  description: The hostname and path pairs excluded from Behavioral DDoS mitigation actions.
                  items:
                    additionalProperties: false
                    description: The hostname and path pair combinations excluded from Behavioral DDoS mitigation actions.
                    properties:
                      hosts:
                        description: Hostnames in host and path pairs to exclude.
                        items:
                          type: string
                        minItems: 1
                        type: array
                      paths:
                        description: Paths in host and path pairs to exclude.
                        items:
                          type: string
                        minItems: 1
                        type: array
                    required:
                    - hosts
                    - paths
                    type: object
                    x-akamai:
                      file-path: schemas/behavioral-ddos-host-path-exception.yaml
                  minItems: 0
                  type: array
                hostnames:
                  description: The hostnames that you want to be protected by the Behavioral DDoS profile.
                  items:
                    type: string
                  minItems: 1
                  type: array
                name:
                  description: The profile's unique name.
                  type: string
                profileId:
                  description: __Read-only__ Uniquely identifies the Behavioral DDoS profile.
                  format: int64
                  readOnly: true
                  type: integer
                sensitivity:
                  description: Sensitivity level, specify `CONSERVATIVE` to provide tolerance for more substantial traffic deviations, `MODERATE` to provide tolerance for traffic fluctuations, or `STRICT` for high-security environments, where minor deviations in traffic might signal a potential DDoS attack.
                  enum:
                  - CONSERVATIVE
                  - MODERATE
                  - STRICT
                  type: string
                sensitivityOverrides:
                  description: Sensitivity overrides for one or more hostname and path pairs.
                  items:
                    additionalProperties: false
                    description: Hostnames and path, overriding the global sensitivity setting.
                    properties:
                      host:
                        description: Hostname in host and path pair to override.  Wildcards are allowed (`*` and `?`).
                        type: string
                      path:
                        description: Path in host and path pair to override.  Wildcards are allowed (`*` and `?`).
                        type: string
                      sensitivity:
                        description: Sensitivity level, specify `CONSERVATIVE` to provide tolerance for more substantial traffic deviations, `MODERATE` to provide tolerance for traffic fluctuations, or `STRICT` or high-security environments, where minor deviations in traffic might signal a potential DDoS attack.
                        enum:
                        - CONSERVATIVE
                        - MODERATE
                        - STRICT
                        type: string
                    required:
                    - host
                    - path
                    - sensitivity
                    type: object
                    x-akamai:
                      file-path: schemas/behavioral-ddos-sensitivity-override.yaml
                  minItems: 0
                  type: array
                suspend:
                  additionalProperties: false
                  description: Temporarily disable mitigation for a specific hostname, with the flexibility to choose the duration of its suspension.
                  properties:
                    fromDate:
                      description: The start ISO 8601 timestamp of suspension.
                      format: date-time
                      type: string
                    hostnames:
                      description: Hostnames to suspend for a specified duration.
                      items:
                        type: string
                      minItems: 1
                      type: array
                    toDate:
                      description: The end ISO 8601 timestamp of suspension.
                      format: date-time
                      type: string
                  required:
                  - hostnames
                  - fromDate
                  - toDate
                  type: object
                  x-akamai:
                    file-path: schemas/behavioral-ddos-suspend.yaml
                updateDate:
                  description: __Read-only__ The ISO 8601 timestamp when you last updated the Behavioral DDoS profile.
                  format: date-time
                  readOnly: true
                  type: string
                updatedBy:
                  description: __Read-only__ Username who last updated the Behavioral DDoS profile.
                  readOnly: true
                  type: string
                used:
                  description: __Read-only__ Whether you're currently using the Behavioral DDoS profile.
                  readOnly: true
                  type: boolean
              required:
              - name
              - sensitivity
              - hostnames
              type: object
              x-akamai:
                file-path: schemas/behavioral-ddos-profile.yaml
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                bypassCondition:
                  atomicConditions:
                  - checkIps: connecting
                    className: NetworkListCondition
                    positiveMatch: true
                    value:
                    - 100065_IPLIST
                  - className: RequestHeaderCondition
                    name:
                    - Content-Type
                    nameWildcard: true
                    positiveMatch: true
                    value:
                    - application/json
                    valueCase: false
                    valueWildcard: true
                configId: 1
                configVersion: 1
                createDate: '2025-02-05T14:00:00Z'
                createdBy: jkowalski
                description: This is a description of the profile
                exceptions:
                - hosts:
                  - secure.host1.com
                  - help.host3.com
                  paths:
                  - /path1
                  - /path2
                  - /path3
                hostnames:
                - secure.host1.com
                - www.host2.com
                - help.host3.com
                - info.host4.com
                name: My first BDE profile
                profileId: 100
                sensitivity: STRICT
                sensitivityOverrides:
                - host: info.host4.com
                  path: /path3
                  sensitivity: MODERATE
                suspend:
                  fromDate: '2025-02-20T14:00:00Z'
                  hostnames:
                  - secure.host1.com
                  toDate: '2025-03-20T14:00:00Z'
                updateDate: '2025-02-05T14:00:00Z'
                updatedBy: adevi
                used: true
              schema:
                additionalProperties: false
                description: Contains details about a Behavioral DDoS profile.
                properties:
                  bypassCondition:
                    additionalProperties: false
                    description: Exempts specific clients from being processed by the Behavioral DDoS profile.
                    properties:
                      atomicConditions:
                        description: Specify one or more types of conditions to match on. You can match on client lists, request headers, or both.
                        items:
                          oneOf:
                          - additionalProperties: false
                            description: Collects data needed for condition matches on request headers.
                            properties:
                              className:
                                description: Choose `RequestHeaderCondition` to match a header from the requesting client to the specified header.
                                enum:
                                - RequestHeaderCondition
                                type: string
                              name:
                                description: Use `name` to check whether the specified header exists.
                                items:
                                  minLength: 1
                                  type: string
                                minItems: 1
                                type: array
                                uniqueItems: true
                              nameWildcard:
                                description: Whether to interpret `?` and `*` as wildcards in the specified `name`.
                                type: boolean
                              positiveMatch:
                                description: __Read-only__ Whether the condition triggers on a match or lack of match.
                                readOnly: true
                                type: boolean
                              value:
                                description: Unique header values. Use both `value` and `name` to check whether the requesting client’s header matches the specified headers.
                                items:
                                  minLength: 1
                                  type: string
                                minItems: 0
                                nullable: true
                                type: array
                                uniqueItems: true
                              valueCase:
                                description: Whether to consider case when matching header values, `true` for case-sensitive matches.
                                type: boolean
                              valueWildcard:
                                description: Whether to interpret `?` and `*` as wildcards in the specified `value`.
                                type: boolean
                            required:
                            - className
                            - name
                            title: RequestHeaderCondition
                            type: object
                            x-akamai:
                              file-path: schemas/behavioral-ddos-bypass-request-header-condition.yaml
                          - additionalProperties: false
                            description: Collects data needed for condition matches on client lists and network lists.
                            properties:
                              checkIps:
                                description: __Read-only__ Whether the connecting IP or both the connecting IP and `X-Forwarded-For` (XFF) header match on the client list or network list. Behavioral DDoS bypass supports `connecting` only.
                                enum:
                                - connecting
                                readOnly: true
                                type: string
                              className:
                                description: Choose `NetworkListCondition` to match the requesting client's identifier, like IP, GEO, ASN or TLS fingerprint, against the specified client or network list. The only currently supported syntax is `NetworkListCondition`.
                                enum:
                                - NetworkListCondition
                                type: string
                              positiveMatch:
                                description: __Read-only__ Whether the condition triggers on a match or lack of match.
                                readOnly: true
                                type: boolean
                              value:
                                description: Identifies the client list or network list.
                                items:
                                  minLength: 1
                                  type: string
                                minItems: 0
                                nullable: true
                                type: array
                                uniqueItems: true
                            required:
                            - className
                            - value
                            title: NetworkListCondition
                            type: object
                            x-akamai:
                              file-path: schemas/behavioral-ddos-bypass-client-list-condition.yaml
                        minItems: 1
                        type: array
                    type: object
                  configId:
                    description: Uniquely identifies the security configuration.
                    format: int64
                    type: integer
                  configVersion:
                    description: The security configuration version.
                    type: integer
                  createDate:
                    description: __Read-only__ The ISO 8601 timestamp when you created the Behavioral DDoS profile.
                    format: date-time
                    readOnly: true
                    type: string
                  createdBy:
                    description: __Read-only__ The username of the person who created the Behavioral DDoS profile.
                    readOnly: true
                    type: string
                  description:
                    description: A description of the profile.
                    type: string
                  exceptions:
                    description: The hostname and path pairs excluded from Behavioral DDoS mitigation actions.
                    items:
                      additionalProperties: false
                      description: The hostname and path pair combinations excluded from Behavioral DDoS mitigation actions.
                      properties:
                        hosts:
                          description: Hostnames in host and path pairs to exclude.
                          items:
                            type: string
                          minItems: 1
                          type: array
                        paths:
                          description: Paths in host and path pairs to exclude.
                          items:
                            type: string
                          minItems: 1
                          type: array
                      required:
                      - hosts
                      - paths
                      type: object
                      x-akamai:
                        file-path: schemas/behavioral-ddos-host-path-exception.yaml
                    minItems: 0
                    type: array
                  hostnames:
                    description: The hostnames that you want to be protected by the Behavioral DDoS profile.
                    items:
                      type: string
                    minItems: 1
                    type: array
                  name:
                    description: The profile's unique name.
                    type: string
                  profileId:
                    description: __Read-only__ Uniquely identifies the Behavioral DDoS profile.
                    format: int64
                    readOnly: true
                    type: integer
                  sensitivity:
                    description: Sensitivity level, specify `CONSERVATIVE` to provide tolerance for more substantial traffic deviations, `MODERATE` to provide tolerance for traffic fluctuations, or `STRICT` for high-security environments, where minor deviations in traffic might signal a potential DDoS attack.
                    enum:
                    - CONSERVATIVE
                    - MODERATE
                    - STRICT
                    type: string
                  sensitivityOverrides:
                    description: Sensitivity overrides for one or more hostname and path pairs.
                    items:
                      additionalProperties: false
                      description: Hostnames and path, overriding the global sensitivity setting.
                      properties:
                        host:
                          description: Hostname in host and path pair to override.  Wildcards are allowed (`*` and `?`).
                          type: string
                        path:
                          description: Path in host and path pair to override.  Wildcards are allowed (`*` and `?`).
                          type: string
                        sensitivity:
                          description: Sensitivity level, specify `CONSERVATIVE` to provide tolerance for more substantial traffic deviations, `MODERATE` to provide tolerance for traffic fluctuations, or `STRICT` or high-security environments, where minor deviations in traffic might signal a potential DDoS attack.
                          enum:
                          - CONSERVATIVE
                          - MODERATE
                          - STRICT
                          type: string
                      required:
                      - host
                      - path
                      - sensitivity
                      type: object
                      x-akamai:
                        file-path: schemas/behavioral-ddos-sensitivity-override.yaml
                    minItems: 0
                    type: array
                  suspend:
                    additionalProperties: false
                    description: Temporarily disable mitigation for a specific hostname, with the flexibility to choose the duration of its suspension.
                    properties:
                      fromDate:
                        description: The start ISO 8601 timestamp of suspension.
                        format: date-time
                        type: string
                      hostnames:
                        description: Hostnames to suspend for a specified duration.
                        items:
                          type: string
                        minItems: 1
                        type: array
                      toDate:
                        description: The end ISO 8601 timestamp of suspension.
                        format: date-time
                        type: string
                    required:
                    - hostnames
                    - fromDate
                    - toDate
                    type: object
                    x-akamai:
                      file-path: schemas/behavioral-ddos-suspend.yaml
                  updateDate:
                    description: __Read-only__ The ISO 8601 timestamp when you last updated the Behavioral DDoS profile.
                    format: date-time
                    readOnly: true
                    type: string
                  updatedBy:
                    description: __Read-only__ Username who last updated the Behavioral DDoS profile.
                    readOnly: true
                    type: string
                  used:
                    description: __Read-only__ Whether you're currently using the Behavioral DDoS profile.
                    readOnly: true
                    type: boolean
                required:
                - name
                - sensitivity
                - hostnames
                type: object
                x-akamai:
                  file-path: schemas/behavioral-ddos-profile.yaml
          description: Successfully created a Behavioral DDoS profile.
        '400':
          content:
            application/problem+json:
              example:
                detail: The request could not be understood by the server due to malformed syntax.
                instance: https://problems.luna.akamaiapis.net/appsec/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                status: 400
                title: Bad Request
                type: https://problems.luna.akamaiapis.net/appsec/error-types/BAD-REQUEST
              schema:
                additionalProperties: true
                description: Details the errors you can receive.
                properties:
                  detail:
                    description: The detailed error message.
                    type: string
                  fieldErrors:
                    description: Pointers to fields for which invalid input was provided, whose values are messages detailing the reason this input was invalid for this field.
                    type: object
                  instance:
                    description: The non-referenceable URI that indicates the error instance.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 404
                    type: integer
                  title:
                    description: The error title.
                    example: Not Found
                    type: string
                  type:
                    description: The URL for the error type.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-types/NOT-FOUND
                    type: string
                required:
                - title
                - type
                - detail
                - instance
                - status
                type: object
                x-akamai:
                  file-path: schemas/problem-details.yaml
          description: '[Bad request](https://techdocs.akamai.com/application-security/reference/400). Invalid request body or URL parameter input.'
          x-akamai:
            file-path: errors/400.yaml
        '401':
          content:
            application/problem+json:
              example:
                detail: The signature does not match
                instance: https://problems.luna.akamaiapis.net/appsec/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                status: 401
                title: Not authorized
                type: https://problems.luna-dev.akamaiapis.net/-/pep-authn/deny
              schema:
                additionalProperties: true
                d

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/akamai/refs/heads/main/openapi/akamai-behavioral-ddos-profiles-api-openapi.yml