Akamai API Security URL protection policies API

openapi: 3.0.0
info:
  description: 'Manage your configurations for Kona Site Defender,

    Web Application Protector, and Client Reputation.

    '
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: 'Akamai: Application Security Activation history URL protection policies API'
  version: v1
servers:
- url: https://{hostname}/appsec/v1
tags:
- description: Manage your URL protection policies.
  name: URL protection policies
paths:
  /configs/{configId}/versions/{versionNumber}/url-protections:
    parameters:
    - description: A unique identifier for each configuration.
      example: '{{configId}}'
      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.
      example: '{{versionNumber}}'
      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/url-protections.yaml
      path-info: /configs/{configId}/versions/{versionNumber}/url-protections
    post:
      description: Creates a new URL protection policy 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-url-protection-policies
      operationId: post-url-protection-policies
      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).
        example: '{{accountSwitchKey}}'
        in: query
        name: accountSwitchKey
        required: false
        schema:
          example: 1-5C0YLB:1-8BYUX
          type: string
      requestBody:
        content:
          application/json:
            example:
              bypassCondition:
                atomicConditions:
                - className: NetworkListCondition
                  value:
                  - 12345_10CLIENTLIST
                  - '54321_123'
                - className: RequestHeaderCondition
                  name:
                  - my-custom-header
                  value:
                  - my-custom-value
              categories:
              - type: BOTS
              - type: CLOUD_PROVIDERS
              - type: PROXIES
              - type: TOR_EXIT_NODES
              - type: PLATFORM_DDOS_INTELLIGENCE
              - listIds:
                - 12345_10CLIENTLIST
                - '54321_123'
                positiveMatch: true
                type: CLIENT_LIST
              description: URL Protection
              hostnamePaths:
              - hostname: api.demo.com
                paths:
                - /login
                - /checkout
                - /history
              intelligentLoadShedding: true
              name: Transaction site protection
              protectionType: MULTIPLE
              rateThreshold: 195
              sheddingThresholdHitsPerSec: 150
            schema:
              additionalProperties: false
              description: Contains details about a URL protection policy.
              properties:
                apiDefinitions:
                  description: The API endpoints to match on in incoming requests. This only applies to the `api` `matchType`.
                  items:
                    additionalProperties: false
                    properties:
                      apiDefinitionId:
                        description: Uniquely identifies each API endpoint.
                        format: int64
                        type: integer
                      definedResources:
                        description: When `true`, match on any resource explicitly added to your API definition without including a `resourceId`. When `false`, you'll need to pass a `resourceId`.
                        type: boolean
                      resourceIds:
                        description: The unique identifiers of the endpoint's resources.
                        items:
                          format: int64
                          type: integer
                        type: array
                      undefinedResources:
                        description: When `true`, match on any resource you have not explicitly added to your API definition without including a `resourceId`.  When `false`, you'll need to pass a `resourceId`.
                        type: boolean
                    required:
                    - apiDefinitionId
                    type: object
                  type: array
                bypassCondition:
                  additionalProperties: false
                  description: Exempts specific clients from being processed by the URL protection policy.
                  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: A list of 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
                              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/url-protection-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. URL protection 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 list or network list.
                              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
                              nullable: true
                              type: array
                              uniqueItems: true
                          required:
                          - className
                          - value
                          title: NetworkListCondition
                          type: object
                          x-akamai:
                            file-path: schemas/url-protection-bypass-client-list-condition.yaml
                      minItems: 1
                      type: array
                  type: object
                categories:
                  description: The traffic categories to perform load shedding on when the origin traffic rate exceeds the load shedding threshold. If `intelligentLoadShedding` is set to `true`, specify one or more categories.
                  items:
                    oneOf:
                    - additionalProperties: false
                      description: Specify one or more load shedding categories for the URL protection policy.
                      properties:
                        type:
                          description: Specify the type of traffic to shed first before reaching the requests per second (RPS) limit. `BOTS` includes bots from Akamai's existing list of known bots. `CLIENT_REPUTATIONS` includes traffic from clients with a bad client reputation score. `CLOUD_PROVIDERS` includes traffic from providers like AWS, Microsoft Azure, and Google Cloud. `PROXIES` includes proxy traffic as determined by IPQualityScore (IPQS) and Akamai EdgeScape. `TOR_EXIT_NODES` includes traffic defined in Akamai's existing network list of nodes. `PLATFORM_DDOS_INTELLIGENCE` includes traffic detected by Akamai's DDOS Intelligence platform.
                          enum:
                          - BOTS
                          - CLIENT_REPUTATIONS
                          - CLOUD_PROVIDERS
                          - PROXIES
                          - TOR_EXIT_NODES
                          - PLATFORM_DDOS_INTELLIGENCE
                          type: string
                      required:
                      - type
                      title: Client list category
                      type: object
                      x-akamai:
                        file-path: schemas/url-protection-category.yaml
                    - additionalProperties: false
                      description: Defines a `CLIENT_LIST` load shedding category for a URL protection policy.
                      properties:
                        listIds:
                          description: A list of client list identifiers to match on.
                          items:
                            type: string
                          type: array
                        positiveMatch:
                          description: Whether the selected client lists match.
                          type: boolean
                        type:
                          description: Specify `CLIENT_LIST` to match on a client list.
                          enum:
                          - CLIENT_LIST
                          type: string
                      required:
                      - type
                      title: Other categories
                      type: object
                      x-akamai:
                        file-path: schemas/url-protection-client-list-category.yaml
                  type: array
                configId:
                  description: Uniquely identifies the security configuration.
                  example: '{{configId}}'
                  format: int64
                  type: integer
                configVersion:
                  description: The security configuration version.
                  example: '{{configVersion}}'
                  type: integer
                createDate:
                  description: __Read-only__ The timestamp when you created the URL protection policy.
                  example: '{{createDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                createdBy:
                  description: __Read-only__ The username of the person who created the URL protection policy.
                  example: '{{createdBy}}'
                  readOnly: true
                  type: string
                description:
                  description: A description of the rate policy.
                  example: '{{description}}'
                  type: string
                hostnamePaths:
                  description: The hostname and path combinations to match on.
                  items:
                    additionalProperties: false
                    description: The hostname and path combinations to match on.
                    properties:
                      hostname:
                        description: The hostnames you choose to match on.
                        type: string
                      paths:
                        description: The list of paths to match on.
                        items:
                          type: string
                        type: array
                    required:
                    - hostname
                    - paths
                    type: object
                    x-akamai:
                      file-path: schemas/url-protection-policy-hostpath.yaml
                  minItems: 1
                  type: array
                intelligentLoadShedding:
                  description: Enable or disable intelligent load shedding. If enabled, traffic that matches the load shedding categories is eligible for shedding if the origin rate exceeds the load shedding threshold.
                  example: '{{intelligentLoadShedding}}'
                  type: boolean
                name:
                  description: The rate policy's unique name.
                  example: '{{name}}'
                  type: string
                policyId:
                  description: __Read-only__ Uniquely identifies the URL protection policy.
                  example: '{{policyId}}'
                  format: int64
                  readOnly: true
                  type: integer
                protectionType:
                  description: If matching on `hostnamePaths`, specify `SINGLE` to match on a hostname and path, or `MULTIPLE` to match on hostname and path combinations.
                  enum:
                  - SINGLE
                  - MULTIPLE
                  example: '{{protectionType}}'
                  type: string
                rateThreshold:
                  description: The allowed hits per second during any five-second interval.
                  example: '{{rateThreshold}}'
                  type: integer
                sheddingThresholdHitsPerSec:
                  description: Specify the threshold value, in hits per second, after which traffic can be shed. The `sheddingThresholdHitsPerSec` value must be between 70%-90% of the `rateThreshold` value. If you enabled `intelligentLoadShedding`, this value is required.
                  example: '{{sheddingThresholdHitsPerSec}}'
                  type: integer
                updateDate:
                  description: __Read-only__ The ISO 8601 timestamp when you last updated the URL protection policy.
                  example: '{{updateDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                updatedBy:
                  description: __Read-only__ Username who last updated the URL protection policy.
                  example: '{{updatedBy}}'
                  readOnly: true
                  type: string
                used:
                  description: __Read-only__ Whether you're currently using the URL protection policy.
                  example: '{{used}}'
                  readOnly: true
                  type: boolean
              required:
              - intelligentLoadShedding
              - rateThreshold
              - name
              type: object
              x-akamai:
                file-path: schemas/url-protection-policy.yaml
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                bypassCondition:
                  atomicConditions:
                  - checkIps: connecting
                    className: NetworkListCondition
                    positiveMatch: true
                    value:
                    - 12345_10CLIENTLIST
                    - '54321_123'
                  - className: RequestHeaderCondition
                    name:
                    - my-custom-header
                    nameWildcard: false
                    positiveMatch: true
                    value:
                    - my-custom-value
                    valueCase: false
                    valueWildcard: false
                categories:
                - type: BOTS
                - listIds:
                  - 12345_10CLIENTLIST
                  - '54321_123'
                  positiveMatch: true
                  type: CLIENT_LIST
                - listIds:
                  - 16656_CPISERVERS
                  positiveMatch: true
                  type: CLIENT_LIST
                - type: CLOUD_PROVIDERS
                - type: PROXIES
                - type: TOR_EXIT_NODES
                - type: PLATFORM_DDOS_INTELLIGENCE
                configId: 43007
                configVersion: 40
                createDate: '2023-04-14T18:58:53Z'
                createdBy: jsmith
                description: URL Protection
                hostnamePaths:
                - hostname: custom.com
                  paths:
                  - /asd
                  - /my-test-path
                intelligentLoadShedding: true
                name: URL Protection
                policyId: 681
                protectionType: MULTIPLE
                rateThreshold: 195
                sheddingThresholdHitsPerSec: 150
                updateDate: '2023-04-26T02:42:28Z'
                updatedBy: jperez
                used: true
              schema:
                additionalProperties: false
                description: Contains details about a URL protection policy.
                properties:
                  apiDefinitions:
                    description: The API endpoints to match on in incoming requests. This only applies to the `api` `matchType`.
                    items:
                      additionalProperties: false
                      properties:
                        apiDefinitionId:
                          description: Uniquely identifies each API endpoint.
                          format: int64
                          type: integer
                        definedResources:
                          description: When `true`, match on any resource explicitly added to your API definition without including a `resourceId`. When `false`, you'll need to pass a `resourceId`.
                          type: boolean
                        resourceIds:
                          description: The unique identifiers of the endpoint's resources.
                          items:
                            format: int64
                            type: integer
                          type: array
                        undefinedResources:
                          description: When `true`, match on any resource you have not explicitly added to your API definition without including a `resourceId`.  When `false`, you'll need to pass a `resourceId`.
                          type: boolean
                      required:
                      - apiDefinitionId
                      type: object
                    type: array
                  bypassCondition:
                    additionalProperties: false
                    description: Exempts specific clients from being processed by the URL protection policy.
                    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: A list of 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
                                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/url-protection-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. URL protection 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 list or network list.
                                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
                                nullable: true
                                type: array
                                uniqueItems: true
                            required:
                            - className
                            - value
                            title: NetworkListCondition
                            type: object
                            x-akamai:
                              file-path: schemas/url-protection-bypass-client-list-condition.yaml
                        minItems: 1
                        type: array
                    type: object
                  categories:
                    description: The traffic categories to perform load shedding on when the origin traffic rate exceeds the load shedding threshold. If `intelligentLoadShedding` is set to `true`, specify one or more categories.
                    items:
                      oneOf:
                      - additionalProperties: false
                        description: Specify one or more load shedding categories for the URL protection policy.
                        properties:
                          type:
                            description: Specify the type of traffic to shed first before reaching the requests per second (RPS) limit. `BOTS` includes bots from Akamai's existing list of known bots. `CLIENT_REPUTATIONS` includes traffic from clients with a bad client reputation score. `CLOUD_PROVIDERS` includes traffic from providers like AWS, Microsoft Azure, and Google Cloud. `PROXIES` includes proxy traffic as determined by IPQualityScore (IPQS) and Akamai EdgeScape. `TOR_EXIT_NODES` includes traffic defined in Akamai's existing network list of nodes. `PLATFORM_DDOS_INTELLIGENCE` includes traffic detected by Akamai's DDOS Intelligence platform.
                            enum:
                            - BOTS
                            - CLIENT_REPUTATIONS
                            - CLOUD_PROVIDERS
                            - PROXIES
                            - TOR_EXIT_NODES
                            - PLATFORM_DDOS_INTELLIGENCE
                            type: string
                        required:
                        - type
                        title: Client list category
                        type: object
                        x-akamai:
                          file-path: schemas/url-protection-category.yaml
                      - additionalProperties: false
                        description: Defines a `CLIENT_LIST` load shedding category for a URL protection policy.
                        properties:
                          listIds:
                            description: A list of client list identifiers to match on.
                            items:
                              type: string
                            type: array
                          positiveMatch:
                            description: Whether the selected client lists match.
                            type: boolean
                          type:
                            description: Specify `CLIENT_LIST` to match on a client list.
                            enum:
                            - CLIENT_LIST
                            type: string
                        required:
                        - type
                        title: Other categories
                        type: object
                        x-akamai:
                          file-path: schemas/url-protection-client-list-category.yaml
                    type: array
                  configId:
                    description: Uniquely identifies the security configuration.
                    format: int64
                    type: integer
                  configVersion:
                    description: The security configuration version.
                    type: integer
                  createDate:
                    description: __Read-only__ The timestamp when you created the URL protection policy.
                    format: date-time
                    readOnly: true
                    type: string
                  createdBy:
                    description: __Read-only__ The username of the person who created the URL protection policy.
                    readOnly: true
                    type: string
                  description:
                    description: A description of the rate policy.
                    type: string
                  hostnamePaths:
                    description: The hostname and path combinations to match on.
                    items:
                      additionalProperties: false
                      description: The hostname and path combinations to match on.
                      properties:
                        hostname:
                          description: The hostnames you choose to match on.
                          type: string
                        paths:
                          description: The list of paths to match on.
                          items:
                            type: string
                          type: array
                      required:
                      - hostname
                      - paths
                      type: object
                      x-akamai:
                        file-path: schemas/url-protection-policy-hostpath.yaml
                    minItems: 1
                    type: array
                  intelligentLoadShedding:
                    description: Enable or disable intelligent load shedding. If enabled, traffic that matches the load shedding categories is eligible for shedding if the origin rate exceeds the load shedding threshold.
                    type: boolean
                  name:
                    description: The rate policy's unique name.
                    type: string
                  policyId:
                    description: __Read-only__ Uniquely identifies the URL protection policy.
                    format: int64
                    readOnly: true
                    type: integer
                  protectionType:
                    description: If matching on `hostnamePaths`, specify `SINGLE` to match on a hostname and path, or `MULTIPLE` to match on hostname and path combinations.
                    enum:
                    - SINGLE
                    - MULTIPLE
                    type: string
                  rateThreshold:
                    description: The allowed hits per second during any five-second interval.
                    type: integer
            

# --- truncated at 32 KB (133 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/akamai-api-security/refs/heads/main/openapi/akamai-api-security-url-protection-policies-api-openapi.yml