Cisco AMP for Endpoints API

Overview

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:

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":"v1.0.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.
{
  "version": "1.0.0",
  "metadata":{},
  "data":{},
  "errors": []
}

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.

results: {
  "total":1101
}

A lot of the results will be paginated, in which case the result object will look like this:

results: {
  "total":1101,
  "current_item_count":500,
  "index":0,
  "items_per_page":500
}

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

"links": {
  "self": "http://api.sourcefire.com/v1/example?offset=10",
  "next": "http://api.sourcefire.com/v1/example?offset=20",
  "last": "http://api.sourcefire.com/v1/example?offset=0"
}

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.
{
  "error_code": 400,
  "description": "Bad Request",
  "details": [] 
}

Change Log

Filelist

  • Fetches application_blocking list
    GET /v1/file_lists/application_blocking {read-only access needed}

  • Fetches simple_custom_detections list
    GET /v1/file_lists/simple_custom_detections {read-only access needed}

  • Fetches a file list for a given file_list_guid
    GET /v1/file_lists/{:file_list_guid} {read-only access needed}

  • Fetches items for a file list using file_list_guid
    GET /v1/file_lists/{:file_list_guid}/files {read-only access needed}

  • Adds a sha256 to a given file_list using file_list_guid
    POST /v1/file_lists/{:file_list_guid}/files/{:sha256} {read-write access needed}

  • Fetches a particular item for a file_list using file_list_guid and sha256
    GET /v1/file_lists/{:file_list_guid}/files/{:sha256} {read-only access needed}

  • Deletes an item from a file_list using file_list_guid and sha256
    DELETE /v1/file_lists/{:file_list_guid}/files/{:sha256} {read-write access needed}

Group

  • Updates a policy for a given group using group_guid
    PATCH /v1/groups/{:group_guid} {read-write access needed}

Policy

  • Fetches policies
    GET /v1/policies {read-only access needed}

  • Fetches a particular policy using policy_guid
    GET /v1/policies/{:policy_guid} {read-only access needed}

v1

  • Moves a given computer to a particular group
    PATCH /v1/computers/{:connector_guid} {read-write access needed}
Write
Preview