Network Lists API v2

Manages lists of network addresses and countries as a common resource for use in various Akamai security products.

Learn more:

Overview

The Network Lists API allows you to manage a common set of lists for use in various Akamai security products such as Kona Site Defender, Web App Protector, and Bot Manager. Network lists are shared sets of IP addresses, CIDR blocks, or broad geographic areas. Along with managing your own lists, you can also access read-only lists that Akamai dynamically updates for you.

This API version 2 provides support for fast activation, where deploying updated network lists typically takes less than 10 minutes. (During an initial beta period, fast activation is available only to select customers.) Version 2 also provides minor updates to standardize URL endpoint patterns. It consolidates the ability to search for network lists, and to list them as a collection. Viewing these collections is now much faster by default. This API version also removes support for sharing lists across accounts. You should update your tools to migrate away from the superseded Version 1.

Who should use this API

Use this API if you want to programmatically manage whitelists of IP addresses and CIDR blocks under your control, integrating them with security configurations within Akamai products. Use it if you want to leverage Akamai-managed lists for use in your own security monitoring applications. Akamai provides dynamic CIDR block whitelists of popular cloud providers, and blacklists that keep track of threatening sources such as dark-web TOR nodes. You can also integrate IP blacklists from other providers into your network monitoring tools. Otherwise as an alternative to identifying IP addresses as they emerge, you can respond to threat patterns more broadly by blocking traffic from entire countries. You can also use this feature to restrict overall access to your web assets to specific countries.

Getting started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Network Lists, and set the access level to READ-WRITE.

Concurrency control

To make sure different API clients don’t overwrite each other’s data, this API supports optimistic concurrency control for any modifications to network lists.

Whenever you run the Get a network list GET operation, your need to retain the value of the response’s syncPoint and pass it back in when you subsequently run the Update a network list PUT operation. The update operation only succeeds if there haven’t been any interim updates by other API clients. If the update fails, you get a 409 error response.

Note that you only need to pass in the syncPoint value when updating the entire network list object, with or without its complete list of elements. The following operations that only modify the set of elements do not require a syncPoint value:

The response from these operations provide an updated syncPoint value, which you would need for any update to the main network list object, even for a change that doesn’t modify the list of elements.

Partial GET and PUT options

When reading and writing NetworkList objects, you may wish to modify its top-level members rather than its complete list of elements, or other extraneous metadata. The API offers two query parameters, includeElements and extended to speed up GET requests for this top-level data, and to speed up responses that reflect requested changes. When you set includeElements to false, you don’t get the full list of elements. When you set extended to false, you don’t get data about activation status or the object’s creation and latest modification.

Whenever you run the Update a network list operation, you have the option to PUT back this smaller object, omitting many data members from your request, such as the list of elements, without affecting corresponding values. See the NetworkList for overall membership requirements.

API hypermedia

Many of this API’s response objects feature hypermedia links, which allow your API client to navigate directly to related operations on a relevant resource. This additional set of data specifies a contextual href for the resource, along with any non-GET method you need to call it with.

All links objects are arranged as a map, where the object keys serve as descriptive link relations. The following lists these link relations, along with the corresponding API operation they enable.

See the Hypermedia object for more details on the data structure.

The following example shows a set of links for an individual network list:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16", "13.126.0.0/15", "13.210.0.0/15",
        "13.228.0.0/15", "13.230.0.0/15", "13.232.0.0/14",
        "13.236.0.0/14", "13.250.0.0/15", "13.54.0.0/15",
        "13.56.0.0/16", "13.57.0.0/16", "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

Migrate from v1 to v2

The following section describes the functional and structural changes you need to migrate your workflow from v1 to v2 of the API.

The following changes affect all endpoints:

  • The root path for operations on lists changed from v1/network_lists to v2/network-lists.

  • The format of the API’s common error response object now conforms to the HTTP Problem Details specification that’s standard for Akamai APIs. See the Errors section for more details.

  • For all operations that modify network lists, such as by adding or removing list items, the API returns the complete modified network list in the response.

  • The unique-id, sync-point, request-id, and activation-status response members are now named uniqueId, syncPoint, requestId, and activationStatus to align with other Akamai APIs.

  • acgs have been replaced with contracts and groups. acg in responses is renamed to accessControlGroup.

  • APIs now respond with structured hypermedia objects, whose href values allow your API client to navigate to related API operations, optionally using a specified method other than GET.

Changes that affect the List network lists operation:

  • List elements are no longer included in the response by default. To match the original v1 behavior, which includes all elements, set the includeElements query parameter to true.

  • The new API version removes the separate /search endpoint. To search across lists, add a search query parameter to the /network-lists GET operation that specifies the search string. For example:

    v1/network_lists/search?expression=1.1.1.1

    becomes…

    v2/network-lists?search=1.1.1.1

  • This version removes the extended query parameter, which controlled whether to include metadata about updates and initial creation in responses. This metadata always appears in v2 responses.

Changes that affect the Create a new network list operation:

  • You can now specify a contractId and groupId when creating Network Lists.

Changes that affect the Update a network list operation:

  • The /element endpoint is now named /elements. For example:

    v1/network_lists/345_BOTLIST/element?element=123.123.123.123

    becomes…

    v2/network-lists/345_BOTLIST/elements?element=123.123.123.123

  • The POST operation on a network list resource to append a set of elements now uses a separate /append POST endpoint. For example, a POST to:

    v1/network_lists/345_BOTLIST

    now becomes a POST to…

    v2/network-lists/345_BOTLIST/append

Changes that affect the Activate a network list and Get activation status operations:

  • Activations now specify networks as /environments/{env} URL path parameters rather than as query parameters. For example:

    v1/network_lists/345_BOTLIST/status?env=production

    becomes…

    v2/network-lists/345_BOTLIST/environments/PRODUCTION/status

  • The sync-point query parameter now uses a sync-points endpoint path to access history resources. For example:

    v1/network_lists/345_BOTLIST/history?sync%2dpoint=5

    becomes…

    v2/network-lists/345_BOTLIST/sync-points/5/history

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List network lists GET /network-list/v2/network-lists{?includeElements,search,extended,listType}
Create a new network list POST /network-list/v2/network-lists
Get a network list GET /network-list/v2/network-lists/{networkListId}{?extended,includeElements}
Update a network list PUT /network-list/v2/network-lists/{networkListId}{?extended,includeElements}
Delete a network list DELETE /network-list/v2/network-lists/{networkListId}
Append elements to a network list POST /network-list/v2/network-lists/{networkListId}/append
Add an element PUT /network-list/v2/network-lists/{networkListId}/elements{?element}
Remove an element DELETE /network-list/v2/network-lists/{networkListId}/elements{?element}
Activate a network list POST /network-list/v2/network-lists/{networkListId}/environments/{environment}/activate
Get activation status GET /network-list/v2/network-lists/{networkListId}/environments/{environment}/status
Get an activation’s snapshot GET /network-list/v2/network-lists/{networkListId}/sync-points/{syncPoint}/history{?extended}
Update network list details PUT /network-list/v2/network-lists/{networkListId}/details
Get activation details GET /network-list/v2/activations/{activationId}
Subscribe to network lists POST /network-list/v2/notifications/subscribe
Unsubscribe to network lists POST /network-list/v2/notifications/unsubscribe

List network lists

List all network lists available for an authenticated user who belongs to a group, optionally filtered by listType or based on a search string. Results appear within the networkLists array, which might be empty if no network lists are available to the client.

GET /network-list/v2/network-lists{?includeElements,search,extended,listType}

Sample: /network-list/v2/network-lists?includeElements=true&search=192.168.&extended=true&listType=IP

Parameter Type Sample Description
Optional query parameters
extended Boolean true When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide.
includeElements Boolean true If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default false value when listing more than one network list omits the network list’s elements and only provides higher-level metadata.
listType String IP Filters the output to lists of only the given type of network lists if provided, either IP or GEO. This corresponds to the NetworkList object’s type member.
search String 192.168. Only list items that match the specified substring in any network list’s name or list of items.

Status 200 application/json

Object type: NetworkList

Download schema: lists.json

Response Body:

{
    "networkLists": [
        {
            "networkListType": "networkListResponse",
            "accessControlGroup": "KSD\nwith ION 3-13H1234",
            "name": "General List",
            "elementCount": 3011,
            "syncPoint": 22,
            "type": "IP",
            "uniqueId": "25614_GENERALLIST",
            "links": {
                "activateInProduction": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/activate",
                    "method": "POST"
                },
                "activateInStaging": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/STAGING/activate",
                    "method": "POST"
                },
                "appendItems": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST",
                    "method": "POST"
                },
                "retrieve": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST"
                },
                "statusInProduction": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
                },
                "statusInStaging": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
                },
                "update": {
                    "href": "/network-list/v2/network-lists/25614_GENERALLIST",
                    "method": "PUT"
                }
            }
        },
        {
            "networkListType": "networkListResponse",
            "account": "Kona\nSecurity Engineering",
            "accessControlGroup": "Top-Level Group: 3-12DAF123",
            "name": "Ec2 Akamai Network List",
            "elementCount": 235,
            "readOnly": true,
            "syncPoint": 65,
            "type": "IP",
            "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
            "links": {
                "activateInProduction": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
                    "method": "POST"
                },
                "activateInStaging": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
                    "method": "POST"
                },
                "appendItems": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
                    "method": "POST"
                },
                "retrieve": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
                },
                "statusInProduction": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
                },
                "statusInStaging": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
                },
                "update": {
                    "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
                    "method": "PUT"
                }
            }
        },
        {
            "networkListType": "networkListResponse",
            "accessControlGroup": "KSD\nTest - 3-13H5523",
            "name": "GeoList_1913New",
            "elementCount": 16,
            "syncPoint": 2,
            "type": "GEO",
            "uniqueId": "26732_GEOLIST1913",
            "links": {
                "activateInProduction": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/PRODUCTION/activate",
                    "method": "POST"
                },
                "activateInStaging": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/STAGING/activate",
                    "method": "POST"
                },
                "appendItems": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913/append",
                    "method": "POST"
                },
                "retrieve": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913"
                },
                "statusInProduction": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/PRODUCTION/status"
                },
                "statusInStaging": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/STAGING/status"
                },
                "update": {
                    "href": "/network-list/v2/network-lists/26732_GEOLIST1913",
                    "method": "PUT"
                }
            }
        }
    ],
    "links": {
        "create": {
            "href": "/network-list/v2/network-lists/",
            "method": "POST"
        }
    }
}

  1. Specify a search string query parameter if you want to narrow the results based on the name or any of the list elements.

  2. To further narrow results, specify either IP or GEO as a listType query parameter.

  3. Set the includeElements query parameter to true if you want the response to include the complete network list array. Note that enabling when gathering more than one network list may unnecessarily slow the response.

  4. Set the extended query parameter to true if you want details about deployment status and the most recent update.

  5. Make a GET request to /network-list/v2/network-lists{?includeElements,search,extended,listType}.

The response’s networkLists array features a series of NetworkList objects.

Create a new network list

Creates a new network list.

POST /network-list/v2/network-lists

Content-Type: application/json

Object type: NetworkList

Download schema: create.json

Request Body:

{
    "name": "My New Open List",
    "type": "IP",
    "description": "Notes about this network list",
    "list": []
}

Status 201 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. Build a NetworkList object, featuring at least basic information such as name and type of list.

  2. POST the object to /network-list/v2/network-lists.

The full NetworkList reflected in the response features a uniqueId that you can use whenever accessing it later with a networkListId URL parameter.

Get a network list

Gets a network list’s most recent syncPoint version.

GET /network-list/v2/network-lists/{networkListId}{?extended,includeElements}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS?extended=true&includeElements=true

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
Optional query parameters
extended Boolean true When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide.
includeElements Boolean true If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default true value includes the list’s contents.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. Set the extended query parameter to true if you want details about deployment status and the most recent update.

  3. Set the includeElements query parameter to true if you want the response to include the complete network list array.

  4. Make a GET request to /network-list/v2/network-lists/{networkListId}{?extended,includeElements}.

The response features a NetworkList object.

Update a network list

Modify the network list items and properties. Allows you to set the name, description and set of network list items to the resource. The current state of the list will be replaced with the properties and items you provide. The type cannot be changed.

PUT /network-list/v2/network-lists/{networkListId}{?extended,includeElements}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS?extended=true&includeElements=true

Content-Type: application/json

Object type: NetworkList

Download schema: update.json

Request Body:

{
    "name": "My Updated Open List",
    "type": "IP",
    "description": "Updated notes about this network list",
    "syncPoint": 1,
    "list": [
        "13.230.0.0/15",
        "195.7.50.194",
        "50.23.59.233"
    ]
}
Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
Optional query parameters
extended Boolean true When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide.
includeElements Boolean true If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default true value includes the list’s contents.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose the relevant object from the networkLists array whose readOnly member is false, and store its uniqueId.

  2. Run Get a network list to get the network list you want to modify. If you want to modify the full list of elements, make sure the includeElements query parameter is true, as by default. Otherwise you can only modify the network list’s higher-level metadata.

  3. Modify the NetworkList object, leaving the syncPoint value unchanged. Omitting any other data members from the subsequent request leaves corresponding data unchanged.

  4. Set the includeElements query parameter to true if you want the response to include the complete network list array.

  5. Set the extended query parameter to true if you want the response to reflect details about deployment status and the most recent update.

  6. PUT the object to /network-list/v2/network-lists/{networkListId}{?extended,includeElements}.

The response NetworkList reflects the modified object with an incremented syncPoint value. Its size depends on whether you enabled extended and includeElements.

After modifying a network list, run Activate a network list to make it go live.

Delete a network list

Removes a network list. You can only remove network lists that never activated. To deactivate a list, you can empty out its list of elements.

DELETE /network-list/v2/network-lists/{networkListId}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.

Status 200 application/json

Object type: Message

Download schema: message.json

Response Body:

{
    "status": 200,
    "uniqueId": "33501_TESTLIST",
    "syncPoint": 4
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. Make a DELETE request to /network-list/v2/network-lists/{networkListId}.

  3. The response Message provides basic details on the deleted object.

Append elements to a network list

Appends a set of elements to a network list. If the networks list’s type is IP, the submitted list is a series of IP addresses or CIDR blocks. If the type is GEO, it’s a set of two-character country codes. (See the EdgeScape Documentation for more information. For a list of countries, go to Data Codes ⇒ Country Code.)

POST /network-list/v2/network-lists/{networkListId}/append

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/append

Content-Type: application/json

Object type: NetworkList

Download schema: append.json

Request Body:

{
    "list": [
        "201.22.44.12",
        "8.7.6.0/24"
    ]
}
Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. Build a minimal NetworkList object, featuring only a list array of items you want to append.

  3. POST the object to /network-list/v2/network-lists/{networkListId}/append.

  4. The response’s NetworkList object reflects the complete modified list of elements.

Add an element

Adds the specified element to the list. If the network list’s type is IP, the value needs to be a URL-encoded IP address or CIDR block. If the type is GEO, it’s a two-character country code. (See the EdgeScape Documentation for more information. For a list of countries, go to Data Codes ⇒ Country Code.)

PUT /network-list/v2/network-lists/{networkListId}/elements{?element}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/elements?element=174.129.0.0/16

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
Required query parameters
element String 174.129.0.0/16 Specifies the element to add to the network list.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. If the element you want to add is an IP address or CIDR block, the type of the object must be IP. Otherwise if it’s a country code, the type needs to be GEO.

  3. Specify the element you want to add as a query parameter. Make sure to URL-encode any slash characters included in CIDR block values.

  4. Make a PUT request to /network-list/v2/network-lists/{networkListId}/elements{?element}.

  5. The response reflects the NetworkList, including the longer list of elements.

Remove an element

Removes the specified element from the list. If the network list’s type is IP, the value is a URL-encoded IP address or CIDR block. If the type is GEO, it’s a two-character country code.

DELETE /network-list/v2/network-lists/{networkListId}/elements{?element}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/elements?element=174.129.0.0/16

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
Required query parameters
element String 174.129.0.0/16 Specifies the element to remove from the network list.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. If the element you want to remove is an IP address or CIDR block, the type of the object needs to be IP. Otherwise if it’s a country code, it needs to be GEO.

  3. Specify the element you want to remove as a query parameter. Make sure to URL-encode any slash characters included in CIDR block values.

  4. Make a DELETE request to /network-list/v2/network-lists/{networkListId}/elements{?element}.

The response reflects the NetworkList, including the shorter list of elements.

Activate a network list

Activate the most recent syncPoint version of a network list in either the STAGING or PRODUCTION environment.

POST /network-list/v2/network-lists/{networkListId}/environments/{environment}/activate

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/environments/PRODUCTION/activate

Content-Type: application/json

Object type: ActivationRequest

Download schema: activate.json

Request Body:

{
    "comments": "Whitelist IPs of new employees who joined this week",
    "notificationRecipients": [
        "it-team@example.com",
        "security-team@example.com"
    ],
    "fast": false
}
Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
environment String PRODUCTION The environment in which this list’s activation occurs, either STAGING or PRODUCTION.

Status 200 application/json

Object type: ActivationStatus

Download schema: status.json

Response Body:

{
    "activationId": 12345,
    "activationComments": "Whitelist IPs of new employees who joined this week",
    "activationStatus": "PENDING_ACTIVATION",
    "syncPoint": 5,
    "uniqueId": "25614_GENERALLIST",
    "fast": false,
    "dispatchCount": 1,
    "links": {
        "appendItems": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
        },
        "statusInProduction": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
        },
        "syncPointHistory": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
        },
        "update": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
            "method": "PUT"
        },
        "activationDetails": {
            "href": "/network-list/v2/network-lists/activations/12345/"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. Specify an environment of either STAGING or PRODUCTION.

  3. Build an ActivationRequest object, with a set of email notificationRecipients and any accompanying comments to clarify the reason for the activation.

  4. POST the object to /network-list/v2/network-lists/{networkListId}/environments/{environment}/activate.

The ActivationStatus response displays the activationStatus, initially as PENDING_ACTIVATION. From this point, you can:

Get activation status

Shows a network list’s activation status on either the STAGING or PRODUCTION environment. The response reflects standard activation status. For fast activation status, see Get activation details.

GET /network-list/v2/network-lists/{networkListId}/environments/{environment}/status

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/environments/PRODUCTION/status

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
environment String PRODUCTION The environment in which this list’s activation occurs, either STAGING or PRODUCTION.

Status 200 application/json

Object type: ActivationStatus

Download schema: status.json

Response Body:

{
    "activationId": 12345,
    "activationComments": "Whitelist IPs of new employees who joined this week",
    "activationStatus": "PENDING_ACTIVATION",
    "syncPoint": 5,
    "uniqueId": "25614_GENERALLIST",
    "fast": false,
    "dispatchCount": 1,
    "links": {
        "appendItems": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
        },
        "statusInProduction": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
        },
        "syncPointHistory": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
        },
        "update": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
            "method": "PUT"
        },
        "activationDetails": {
            "href": "/network-list/v2/network-lists/activations/12345/"
        }
    }
}

  1. If you don’t already have a networkListId, run the List network lists operation, choose an object from the networkLists array, and store its uniqueId.

  2. Specify an environment of either STAGING or PRODUCTION.

  3. Make a GET request to /network-list/v2/network-lists/{networkListId}/environments/{environment}/status.

The ActivationStatus response object features the network list’s syncPoint version, along with its activationStatus.

Get an activation’s snapshot

Gets a version of a network list in its state when activated, with each version identified by its syncPoint value. You can only get syncPoint versions that have been activated.

GET /network-list/v2/network-lists/{networkListId}/sync-points/{syncPoint}/history{?extended}

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/sync-points/65/history?extended=true

Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.
syncPoint Integer 65 The network list version for which to retrieve the snapshot. This corresponds to the syncPoint the API exchanges for each successive modification to the network list. See Concurrency control for details.
Optional query parameters
extended Boolean true When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide.

Status 200 application/json

Object type: NetworkList

Download schema: network-list.json

Response Body:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

  1. You would typically run this operation based on data available when activating a network list. From the response object, store the activated list’s syncPoint version, and store the uniqueId as a networkListId URL parameter.

  2. Set the extended query parameter to true if you want to know if the network list is currently deployed, or details about its creation or most recent update.

  3. Make a GET request to /network-list/v2/network-lists/{networkListId}/sync-points/{syncPoint}/history{?extended}.

  4. The response’s NetworkList object shows the full set of list elements at the time of activation.

Update network list details

Update a network list’s name or description.

PUT /network-list/v2/network-lists/{networkListId}/details

Sample: /network-list/v2/network-lists/12345_BLACKLISTEDGEOS/details

Content-Type: application/json

Object type: NetworkList

Download schema: update-details.json

Request Body:

{
    "name": "My Updated Open List",
    "description": "Updated notes about this network list"
}
Parameter Type Sample Description
URL parameters
networkListId String 12345_BLACKLISTEDGEOS Unique identifier for each network list.

Status 204

Get activation details

Provides detailed status for a given activation, including progress on fast activation and other audit information, in addition to information ordinarily available from the Get activation status operation.

GET /network-list/v2/activations/{activationId}

Sample: /network-list/v2/activations/130439

Parameter Type Sample Description
URL parameters
activationId Integer 130439 The unique identifier for this activation request.

Status 200 application/json

Object type: ActivationDetails

Download schema: activation-request.json

Response Body:

{
    "activationId": 1303191,
    "createDate": "2018-03-13T10:26:23.659Z",
    "createdBy": "jane.thompson@securedproperty.com",
    "environment": "STAGING",
    "fast": false,
    "networkList": {
        "activationComments": "Whitelist local IPs",
        "activationStatus": "PENDING_ACTIVATION",
        "links": {
            "appendItems": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/append",
                "method": "POST"
            },
            "retrieve": {
                "href": "/networklist-api/38069_INTERNALWHITELIST"
            },
            "statusInProduction": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/environments/PRODUCTION/status"
            },
            "statusInStaging": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/environments/STAGING/status"
            },
            "syncPointHistory": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/sync-points/0/history"
            },
            "update": {
                "href": "/networklist-api/38069_INTERNALWHITELIST",
                "method": "PUT"
            }
        },
        "syncPoint": 0,
        "uniqueId": "38069_INTERNALWHITELIST"
    }
}

  1. When running the Activate a network list operation to activate a network list, store the activationId from the response.

  2. Make a GET request to /network-list/v2/activations/{activationId}.

The response is an ActivationDetails object.

Subscribe to network lists

Specifies a set of email addresses to inform portal account recipients about any changes to a set of network lists.

POST /network-list/v2/notifications/subscribe

Content-Type: application/json

Download schema: subscribe.json

Request Body:

{
    "recipients": [
        "it-team@mycompany.com",
        "security-team@mycompany.com"
    ],
    "uniqueIds": [
        "32055_REPUTATIONWHITELISTDONO",
        "365_AKAMAITOREXITNODES"
    ]
}

Status 204

Unsubscribe to network lists

Unsubscribes the listed users from a set of network lists.

POST /network-list/v2/notifications/unsubscribe

Content-Type: application/json

Download schema: subscribe.json

Request Body:

{
    "recipients": [
        "it-team@mycompany.com",
        "security-team@mycompany.com"
    ],
    "uniqueIds": [
        "32055_REPUTATIONWHITELISTDONO",
        "365_AKAMAITOREXITNODES"
    ]
}

Status 204

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

NetworkList

Encapsulates information about each network list.

Download schema: network-list.json

Sample GET response:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16",
        "13.126.0.0/15",
        "13.210.0.0/15",
        "13.228.0.0/15",
        "13.230.0.0/15",
        "13.232.0.0/14",
        "13.236.0.0/14",
        "13.250.0.0/15",
        "13.54.0.0/15",
        "13.56.0.0/16",
        "13.57.0.0/16",
        "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

NetworkList members

Member Type Required Description
NetworkList: Encapsulates information about each network list.
accessControlGroup String ○ Name of this network list’s access control group (ACG).
account String ○ Name of the account under which the network list was provisioned.
createDate String ○ Read-only. ISO 8601 timestamp indicating when the network list was first created. Available only when using the extended query parameter to retrieve network list data.
createdBy String ○ Read-only. Username of this list’s creator. Available only when using the extended query parameter to retrieve network list data.
description String ○ Detailed description of the list.
elementCount Integer ○ Read-only. Reflects the number of elements in the list array, which may not necessarily appear in the object when retrieving the list with the includeElements query parameter set to false.
expeditedProductionActivationStatus String ○ Read-only. For clients with access to expedited activations on select servers, provides the most recent activation status in the PRODUCTION environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data.
expeditedStagingActivationStatus String ○ Read-only. For clients with access to expedited activations on select servers, provides the most recent activation status in the STAGING environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data.
links Hypermedia ○ Encapsulates the set of API hypermedia to access a set of resources related to this network list. The object is arranged as a hash of keys, each of which represents a link relation.
list Array ○ Defines the network list’s set of elements. If the type is IP, values are any combination of IPv4 addresses, IPv6 addresses, or CIDR blocks. If the type is GEO, values are ISO 3166 two-character country codes. This array does not appear in the object if you retrieve it with the includeElements query parameter set to false.
name String ✓ Display name of the network list.
networkListType String ○ If set to extendedNetworkListResponse, indicates that the current data features members enabled with the extended query parameter. Otherwise a plain networkListResponse value indicates this additional data is absent.
productionActivationStatus String ○ Read-only. The most recent activation status of the current list in the PRODUCTION environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data.
readOnly Boolean ○ Read-only. If true, indicates that you do not have permission to modify the network list. This may indicate either a network list that Akamai manages, or insufficient permission for your API client’s identity to modify a customer-managed list. The default value is false.
stagingActivationStatus String ○ Read-only. The most recent activation status of the current list in the STAGING environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data.
syncPoint Integer ✓ Identifies each version of the network list, which increments each time it’s modified. You need to include this value in any requests to modify the list. See Concurrency control for details.
type String ✓ The network list type, either IP for IP addresses and CIDR blocks, or GEO for two-letter country codes.
uniqueId String ✓ A unique identifier for each network list, corresponding to the networkListId URL parameter.
updateDate String ○ Read-only. ISO 8601 timestamp indicating when the network list was last modified. Available only when using the extended query parameter to retrieve network list data.
updatedBy String ○ Read-only. Username of this list’s creator. Available only when using the extended query parameter to retrieve network list data.

ActivationRequest

Requests a new activation.

Download schema: activate.json

Sample POST request:

{
    "comments": "Whitelist IPs of new employees who joined this week",
    "notificationRecipients": [
        "it-team@example.com",
        "security-team@example.com"
    ],
    "fast": false
}

ActivationRequest members

Member Type Required Description
ActivationRequest: Requests a new activation.
comments String ○ Descriptive text to accompany the activation. This is reflected in the ActivationStatus object’s activationComments member.
fast Boolean ○ Specifies fast metadata activation type, true by default. (After an initial beta period, this member will no longer appear in the object.)
notificationRecipients Array ○ List of email addresses of Portal users who receive an email when this activation of this list is complete. Do not add addresses to this list without the recipients’ consent.
siebelTicketId String ○ If the activation is linked to a Siebel ticket, this identifies the ticket.

ActivationStatus

Represents a network list’s activation status, as the response to the Get activation status operation. (This object may also appear within an outer ActivationDetails envelope.)

Download schema: status.json

Sample GET response:

{
    "activationId": 12345,
    "activationComments": "Whitelist IPs of new employees who joined this week",
    "activationStatus": "PENDING_ACTIVATION",
    "syncPoint": 5,
    "uniqueId": "25614_GENERALLIST",
    "fast": false,
    "dispatchCount": 1,
    "links": {
        "appendItems": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
        },
        "statusInProduction": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
        },
        "syncPointHistory": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
        },
        "update": {
            "href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
            "method": "PUT"
        },
        "activationDetails": {
            "href": "/network-list/v2/network-lists/activations/12345/"
        }
    }
}

ActivationStatus members

Member Type Required Description
ActivationStatus: Represents a network list’s activation status, as the response to the Get activation status operation. (This object may also appear within an outer ActivationDetails envelope.)
activationComments String ○ Further information related to the activation. This reflects the comments from the initial ActivationRequest.
activationId Integer ○ Unique identifier for the most recent activation request. May be absent if the list is inactive, or if this object in embedded within an outer ActivationDetails envelope.
activationStatus String ✓ This network list’s current activation status in the specified environment. See Activation States for details on each activation state.
dispatchCount Integer ○ Number of times we have attempted to deploy this security configuration on the network.
fast Boolean ○ Reflects whether fast metadata activation is in effect. (After an initial beta period, this member will no longer appear in the object.)
links Hypermedia ○ Encapsulates the set of API hypermedia to access a set of resources related to this activation. The object is arranged as a hash of keys, each of which represents a link relation.
syncPoint Integer ✓ The version of the currently activated network list. See Concurrency control for details.
uniqueId String ✓ Read-only. Unique identifier for this network list, corresponding to the networkListId URL parameter.

ActivationDetails

Provides additional details about an activation, as the response to the Get activation details operation.

Download schema: activation-request.json

Sample GET response:

{
    "activationId": 1303191,
    "createDate": "2018-03-13T10:26:23.659Z",
    "createdBy": "jane.thompson@securedproperty.com",
    "environment": "STAGING",
    "fast": false,
    "networkList": {
        "activationComments": "Whitelist local IPs",
        "activationStatus": "PENDING_ACTIVATION",
        "links": {
            "appendItems": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/append",
                "method": "POST"
            },
            "retrieve": {
                "href": "/networklist-api/38069_INTERNALWHITELIST"
            },
            "statusInProduction": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/environments/PRODUCTION/status"
            },
            "statusInStaging": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/environments/STAGING/status"
            },
            "syncPointHistory": {
                "href": "/networklist-api/38069_INTERNALWHITELIST/sync-points/0/history"
            },
            "update": {
                "href": "/networklist-api/38069_INTERNALWHITELIST",
                "method": "PUT"
            }
        },
        "syncPoint": 0,
        "uniqueId": "38069_INTERNALWHITELIST"
    }
}

ActivationDetails members

Member Type Required Description
ActivationDetails: Provides additional details about an activation, as the response to the Get activation details operation.
activationId Integer ✓ Unique identifier for the activation.
createDate String ✓ ISO 8601 timestamp indicating when the network list was first created.
createdBy String ✓ Username of this list’s creator.
environment String ✓ The Akamai network on which this activation was requested, either STAGING or PRODUCTION.
estimate String ○ Estimated time remaining to complete the activation, in ISO 8601 duration format, relative to when this response generated. This member may be omitted under standard activation when fast indicates false.
fast Boolean ○ Reflects whether fast metadata activation was requested. (After an initial beta period, this member will no longer appear in the object.)
initial Boolean ○ Returns true for customers using fast metadata if this is the first deployment this network list in this environment. The initial deployment of a list typically takes about 25 minutes, whereas updates to a already deployed list are much quicker, typically 5 - 10 minutes.
networkList ActivationStatus ✓ Provides details on the activated network list ordinarily available from the Get activation status operation.
status String ○ Reflects lower-level fast activation status. See Activation States for details on possible status values. This member may be omitted under standard activation when fast indicates false, or after activation has completed.

Message

A common object that responds to DELETE requests.

Download schema: message.json

Sample DELETE response:

{
    "status": 200,
    "uniqueId": "33501_TESTLIST",
    "syncPoint": 4
}

Message members

Member Type Required Description
Message: A common object that responds to DELETE requests.
status Integer ✓ HTTP status code used for the response.
syncPoint Integer ○ In cases where a network list still exists after the operation, this is the syncPoint required to perform update or delete operations on the list. See Concurrency control for details.
uniqueId String ○ In cases where a network list still exists after the operation, this is the unique ID required to perform further operations on the network list.

Hypermedia

Encapsulates the set of API hypermedia to access a set of related resources. The object is arranged as a hash of keys, each of which represents a link relation.

Download schema: list-links.json

Hypermedia members

Member Type Required Description
Hypermedia: Encapsulates the set of API hypermedia to access a set of related resources. The object is arranged as a hash of keys, each of which represents a link relation.
activateInProduction Hypermedia.{rel} ○ A link to Activate a network list in the PRODUCTION environment.
activateInStaging Hypermedia.{rel} ○ A link to Activate a network list in the STAGING environment.
activationDetails Hypermedia.{rel} ○ A link to Get activation details.
appendItems Hypermedia.{rel} ○ A link to Append elements to a network list.
retrieve Hypermedia.{rel} ○ A link to Get a network list.
statusInProduction Hypermedia.{rel} ○ A link to Get activation status for the PRODUCTION environment.
statusInStaging Hypermedia.{rel} ○ A link to Get activation status for the STAGING environment.
update Hypermedia.{rel} ○ A link to Update a network list.
Hypermedia.{rel}: A link to Update a network list.
detail String ○ Any additional information about the target of the link.
href String ✓ URL to access or perform the action on a related resource. May be expressed as an absolute server path, or relative to the current URL call.
method String ○ The HTTP method with which to call the href, GET by default.

Activation States

When polling a network list or one of its activations, various members’ enumerated values indicate its current state in either the STAGING or PRODUCTION environments. The following reflects basic, high-level status:

Value Description
INACTIVE The network list is not yet activated.
PENDING_ACTIVATION An activation has launched, but the network list has not yet fully activated.
ACTIVE The network list is currently active.
MODIFIED Indicates that a previous syncPoint version of the network list is currently active, and any subsequent modifications may need to be activated.
PENDING_DEACTIVATION An activation for another syncPoint version of the network list has launched, but it has not yet fully rendered this version INACTIVE.
FAILED The network list has failed to activate.

The following alternate set, which appears as values in the ActivationDetails object’s status member, reflects lower-level fast activation states:

Value Description
RECEIVED The activation request has been received, and is being processed.
LIVE The activation is in the process of deploying across the environment.
DEPLOYED The activation is deployed across the environment, and is being checked for stability.
ACTIVATED The activation is successfully deployed across the environment.
FAILED The activation failed.
ROLLBACK A cancellation request is being processed.
CANCELING The activation partly deployed, but is now being cancelled.
DEACTIVATED A requested deactivation successfully completed across the environment.
STOPPED A requested cancellation or deactivation has been completed across the environment.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

This API’s error responses follow the HTTP Problem Details standard. An additional fieldErrors object features an entry array listing specific problems. Each entry lists at least one value criteria that may have triggered the failure.

The following shows a sample error response:

{
    "detail": "Validation failed",
    "instance": "https://problems.luna.akamaiapis.net/network-lists-activation/error-instances/0835dedb-9d01-4178-985b-c93c7f5fcfa8",
    "status": 400,
    "title": "Invalid Input Error",
    "type": "https://problems.luna.akamaiapis.net/network-lists-activation/error-types/INVALID-INPUT-ERROR",
    "fieldErrors": {
        "entry": [
            {
                "key": "createWithPost.arg0",
                "value": [ "Invalid network list type: null" ]
            },
            {
                "key": "name",
                "value": [ "may not be empty" ]
            },
            {
                "key": "type",
                "value": [
                    "Values cannot be null or empty.",
                    "may not be null"
                ]
            }
        ]
    }
}

HTTP status codes

The following lists the full range of response codes the API may generate:

Code Description
200 The operation was successful.
201 Resource successfully created.
400 Bad Request.
403 Access is forbidden.
404 Resource not found.
409 Conflict with the resource’s current syncPoint state. See Concurrency control for details.
500 Internal server error.

Last modified: 12/28/2018