Cisco AMP for Endpoints API

1 Making Requests
- 1.1 Generating Client ID and API Key
2 Rate Limits
3 Request Errors
- 3.1 JSON Envelope format
4 Metadata section
- 4.1 Links
- 4.2 Results
- 4.3 Links
- 4.4 Example of a paginated set of links
- 4.5 Error

Making Requests

Wherever possible, we suggest using the Accept-Encoding: gzip header.

All API requests must use HTTP Basic Auth.

Generating Client ID and API Key

Log in to your AMP for Endpoints Console.
Go to Accounts > Business Settings.
Click Configure API Credentials under Features to generate the Client ID and secure API Key.

Once you have the API client ID and API key, you can make the API calls as follows:

https://<your_client_id>:<your_api_key>@<api_endpoint>

Alternatively you can use Basic HTTP Authentication. Base 64 encode the string ":", and send that prefixed with the string "Basic" as the authorization header. For instance, if your client_id was 1234, and your api_key was "atest", then it would be base64 encoded to "MTIzNDphdGVzdA==", and your header would be:

Authorization: Basic MTIzNDphdGVzdA==

For more information see RFC 1945: http://tools.ietf.org/html/rfc1945#section-11.1

Without proper HTTP Basic auth, the API will respond with an error as follows:

{
"version":"v0.1.0",
"data":{},
"errors":[{
   "error_code":401,
  "description":"Unauthorized",
  "details":["Unknown API key or Client ID"]
 }]
}

Rate Limits

API Clients are allowed to make a limited number of requests every hour. Each API response will include HTTP headers detailing the status of their rate limit. If the limit is overrun, then an HTTP 429 Error will be returned.

X-Rate-Limit-Limit - Total allowed requests in the current period.
X-Rate-Limit-Remaining - Requests left.
X-Rate-Limit-Reset - Number of seconds before the limit is reset.

Request Errors

If you make a request that contains an unexpected parameter or invalid request entity, then a 400 Bad Request will be sent back, and the error will describe which fields were problematic.

JSON Envelope format

All data returned by the API will be in the following format:

version - The version number of the API returning the request. This version number uses Semantic Versioning (Major.Minor.Bugfix).
metadata - Metadata associated with the request, such as pagination information.
data - The data returned by the server. See the documentation for the format of this object.
errors - Request errors, if any.

Metadata section

Links

Links describing the returned resource. In the case of a result set, any pagination links will be here.

Results

In most cases, the API will be returning you a list of results in the data section. The results object gives you information as to how many results were returned.

A lot of the results will be paginated, with a current limit of 500 results in the response. In this case the result object will look like this:

To get the next set of 500 results, or any other offset, most queries support a offset parameter like so:

Links

A links object describes locations where one can retrieve more information about the information described, either the whole document, or elements inside of it.

Example of a paginated set of links

Error

Errors may be the direct response of the API such as a bad request or a server error.

error_code - HTTP status Code
description - Short description of the error.
details - An array of strings with longer-form description of the error, if available.

UI Provisioning-

Device Configuration: Cisco AMP