Chef Automate API Documentation (version not set)

Download OpenAPI specification:Download

E-mail: support@chef.io URL: https://www.chef.io/support/ License: Apache 2.0 Terms of Service

Authentication

The Chef Automate API typically uses an API token passed in the header of your API request.

To create admin token can and set it as an environment variable use the following command:

export TOKEN=`chef-automate iam token create <TOKEN-NAME> --admin`

An admin token has unlimited access the entire Chef Automate API.

Pass the token as part of the API call. For example:

curl -s -H "api-token: $TOKEN" https://automate.example.com/apis/iam/v2/policies -v

To create api tokens with limited permissions, use your admin token to create a standard token. You can then write a policy that exactly defines the API access for the standard token.

In this example, the curl command creates the new token and the export command saves it as an environment variable with the name "TOKEN2".

curl -s -H "api-token: $TOKEN" -d '{"name":"New Token", "id":"new-token"}' https://automate.example.com/apis/iam/v2/tokens
  {
    "token": {
      "id": "new-token",
      "name": "New Token",
      "value": "bww8EEpr39_eYMnQ2zybtrP9uzk=",
      "active": true,
      "created_at": "2020-02-26T19:36:07Z",
      "updated_at": "2020-02-26T19:36:07Z",
      "projects": []
    }
  }

export TOKEN2=bww8EEpr39_eYMnQ2zybtrP9uzk=

The Chef Automate documentation covers policies, authentication, and authorization in greater detail.

API Tokens explains authentication in Chef Automate.
Authorization Overview explains authorization in Chef Automate.

Status Codes

Status Code	Name	Description	Remark
200	OK	Correct Id, Auth token and JSON body	The API worked as expected.
400	Bad Request	Wrong JSON body	The JSON body contains a key or value missing, sometimes when there is no JSON request passed. In some APIs like `IAM Project Rules`, the API request body validation is given the highest preference. And will return this error even before the Auth token validation.
401	Unauthorized	Wrong Auth token	Wrong or no auth token provided.
403	Forbidden	Unauthorized access to Resources	Unauthorised Resource ID is passed to the API. The error is returned in case of no Auth token is passed for some APIs like `Node Export` and `ReportExport`.
404	Not Found	Wrong Id in URL	Wrong or no Id while creating, updating, retrieving, or deleting resources.
409	Conflict	Existing id	Existing resource id provided while creating resources.
405	Method Not Allowed	Server does support the method	Server knows the request, but unfortunately, the target resource does not have a method to serve the request.
500	Internal Server Error	Server encountered error	Generic status code returned while processing an invalid request or server logics.
503	Service Unavailable	Server is down or unable to serve	Generic status code returned when the server gets too busy or into an unserviceable state. This can be because of overwhelming requests like calling `Bulk Delete Nodes by Filter` without JSON body.

Reporting

List Controls

Lists controls from the last run, with optional filtering. Supports filtering,pagination but not sorting. Limited to 100 results by default.

Authorization Action:

compliance:controlItems:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) The criteria used to filter the controls returned.
page_number	integer <int32> (The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results. (Default 1))
size	integer <int32> The maximum number of controls to return (Default 100).
text	string The term to use to match resources on.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"page_number": 0,
"size": 0,
"text": "string"
}

Response samples

200
default

Content type

application/json

{"control_items": [{"control_summary": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"impact": 0,
"profile": {"id": "string",
"name": "string",
"status": "string",
"title": "string",
"version": "string"
},
"title": "string",
"waivers": [{"expiration_date": "string",
"justification": "string",
"waived_str": "string",
"waiver_summary": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
}
}
]
}
],
"control_summary_totals": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
}
}

List Controls Search

Lists controls from the last run, with optional filtering. Supports filtering,pagination but not sorting. Limited to 100 results by default. Gets the summary of each control.

The API supports date range filters when end_time is the current time and start_time is any time in last 90 days. In case, the end_time is any date other than the current date, the API would return data only for the end_time.

Example:

{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page_number":1, "size": 3,
}

Authorization Action:

compliance:controlItems:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) The criteria used to filter the controls returned.
page_number	integer <int32> (The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results. (Default 1))
size	integer <int32> The maximum number of controls to return (Default 100).
text	string The term to use to match resources on.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"page_number": 0,
"size": 0,
"text": "string"
}

Response samples

200
default

Content type

application/json

{"control_items": [{"control_summary": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"impact": 0,
"profile": {"id": "string",
"name": "string",
"status": "string",
"title": "string",
"version": "string"
},
"title": "string",
"waivers": [{"expiration_date": "string",
"justification": "string",
"waived_str": "string",
"waiver_summary": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
}
}
]
}
],
"control_summary_totals": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
}
}

Export reports

Stream reports in JSON (default) or CSV format.

Supports filtering, but not pagination or sorting.

Include the value csv for the type parameter in the request to receive CSV formatted data. Including more than one value for profile_id, or profile_name is not allowed. Including values for both profile_id and profile_name in one request is not allowed.

Example:

'{"type":"csv","filters":[{"type":"start_time","values":["2019-09-16T00:00:00Z"]},{"type":"end_time","values":["2019-09-18T23:59:59Z"]}, {"type":"environment","values":["_default"]}]}'

Request Body schema: application/json
required

	Array of objects (Filters to apply to the query)
name	string Name of the profile (as defined in `inspec.yml`).
order	string (chef.automate.api.compliance.profiles.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC"
owner	string Automate user associated with the profile.
page	integer <int32> Page of results requested.
per_page	integer <int32> Number of results to return per page.
sort	string Field on which to sort.
version	string Version of the profile (as defined in `inspec.yml`).

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"name": "string",
"order": "ASC",
"owner": "string",
"page": 0,
"per_page": 0,
"sort": "string",
"version": "string"
}

Response samples

200

Content type

application/json

{"content": "string"
}

Export node reports

Stream historical reports for a single node in JSON (default) or CSV format.

Supports filtering, but not pagination or sorting. Requires one node_id filter.

Include the value csv for the type parameter in the request to receive CSV formatted data. Including more than one value for profile_id, profile_name, or node_id is not allowed. Including values for both profile_id and profile_name in one request is not allowed. Limited to 9999 results.

Example:

'{"type":"csv","filters":[{"type":"start_time","values":["2019-09-16T00:00:00Z"]},{"type":"end_time","values":["2019-09-18T23:59:59Z"]}, {"type":"node_id","values":["9b9f4e51-b049-4b10-9555-10578916e149"]}]}'

Request Body schema: application/json
required

	Array of objects (Filters to apply to the query)
name	string Name of the profile (as defined in `inspec.yml`).
order	string (chef.automate.api.compliance.profiles.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC"
owner	string Automate user associated with the profile.
page	integer <int32> Page of results requested.
per_page	integer <int32> Number of results to return per page.
sort	string Field on which to sort.
version	string Version of the profile (as defined in `inspec.yml`).

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"name": "string",
"order": "ASC",
"owner": "string",
"page": 0,
"per_page": 0,
"sort": "string",
"version": "string"
}

Response samples

200

Content type

application/json

{"content": "string"
}

Show Node Header Info From Report ID

Show specific details about node, report and metadate provided the report ID. Supports filtering, but not pagination or sorting.

Authorization Action:

compliance:nodeheader:get

path Parameters

id

required

string

Unique identifier.

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"end_time": "2019-08-24T14:15:22Z",
"environment": "string",
"node_id": "string",
"node_name": "string",
"platform": {"full": "string",
"name": "string",
"release": "string"
},
"profiles": [{"name": "string",
"status": "string",
"status_message": "string"
}
],
"roles": ["string"
],
"status": "string",
"status_message": "string",
"version": "string"
}

Show Node by ID

Show a specific node by ID. Supports filtering by profile or control. Does not support pagination or sorting.

Authorization Action:

compliance:reportNodes:get

path Parameters

id

required

string

Unique identifier.

Responses

Response samples

200
default

Content type

application/json

{"environment": "string",
"id": "string",
"latest_report": {"controls": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"status": "string"
},
"name": "string",
"platform": {"full": "string",
"name": "string",
"release": "string"
},
"profiles": [{"full": "string",
"id": "string",
"name": "string",
"status": "string",
"version": "string"
}
],
"tags": [{"key": "string",
"value": "string"
}
]
}

List Nodes

List all nodes, with optional filtering, pagination, and sorting. Max return payload size is 4MB, use pagination to fetch remaining data.

Sort parameter	Sort value
environment	environment.lower
latest_report.controls.failed.critical	controls_sums.failed.critical
latest_report.controls.failed.total	controls_sums.failed.total
latest_report.end_time (default)	end_time
latest_report.status	status
name	node_name.lower
platform	platform.full
status	status

The API supports date range filters when end_time is the current time and start_time is any time in last 90 days. In case, the end_time is any date other than the current date, the API would return data only for the end_time.

Example:

{
"filters":[
{"type":"environment","values":["dev*"]},
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
],
"page":1,"per_page":100,
"sort":"environment","order":"ASC"
}

Authorization Action:

compliance:reportNodes:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"nodes": [{"environment": "string",
"id": "string",
"latest_report": {"controls": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"status": "string"
},
"name": "string",
"platform": {"full": "string",
"name": "string",
"release": "string"
},
"profiles": [{"full": "string",
"id": "string",
"name": "string",
"status": "string",
"version": "string"
}
],
"tags": [{"key": "string",
"value": "string"
}
]
}
],
"total": 0,
"total_failed": 0,
"total_passed": 0,
"total_skipped": 0,
"total_waived": 0
}

List Profiles

List all profiles in use, with optional filtering. Supports pagination, filtering, and sorting. Valid sort fields: name, title

The API supports date range filters when end_time is the current time and start_time is any time in last 90 days. In case, the end_time is any date other than the current date, the API would return data only for the end_time.

Example:

{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page":1, "per_page": 3,
}

Authorization Action:

compliance:reportProfiles:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"counts": {"failed": 0,
"passed": 0,
"skipped": 0,
"total": 0,
"waived": 0
},
"profiles": [{"id": "string",
"name": "string",
"status": "string",
"title": "string",
"version": "string"
}
]
}

List Report IDs

List all IDs for the latest report for each node, with optional filtering. Supports filtering, but not pagination or sorting. Including more than one value for profile_id, or profile_name is not allowed. Including values for both profile_id and profile_name in one request is not allowed. Max return payload size is 4MB.

Authorization Action:

compliance:reportids:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"ids": ["string"
],
"report_data": [{"end_time": "2019-08-24T14:15:22Z",
"id": "string"
}
]
}

List Control Info

Lists controls from the last run, with optional filtering. Supports filtering and pagination. Maximum 100 search can be made when specifying the pagination from and size. Sum of from+size should be less that 100. By default 10 results will be returned. Authorization Action:

compliance:ControlElements:list

path Parameters

id

required

string

Unique identifier.

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"control_elements": [{"id": "string",
"impact": 0,
"profile": "string",
"profile_id": "string",
"results": 0,
"status": "string",
"title": "string"
}
]
}

Export reports

Export multiple reports. Supports filtering by profile or control. API returns an acknowledgement ID.

Authorization Action:

compliance:reports:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"acknowledgement_id": "string"
}

List Reports

Makes a list of reports. Adding a filter makes a list of all node reports that meet the filter criteria. Supports pagination, filtering, and sorting. Max return payload size is 4MB, use pagination to fetch remaining data.

Valid sort fields: latest_report.controls.failed.critical, latest_report.controls.failed.total, latest_report.end_time, latest_report.status, node_name

Example:

{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page":1, "per_page": 3,
"sort": "latest_report.status", "order": "ASC"
}

Authorization Action:

compliance:reports:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"reports": [{"controls": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"ipaddress": "string",
"node_id": "string",
"node_name": "string",
"status": "string"
}
],
"total": 0
}

Show Report by ID

Show a specific report by ID. Supports filtering, but not pagination or sorting. Including more than one value for profile_id, or profile_name is not allowed. Including values for both profile_id and profile_name in one request is not allowed.

Authorization Action:

compliance:reports:get

path Parameters

id

required

string

Unique identifier.

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) Filters applied to the report results.
id	string Unique identifier.
order	string (chef.automate.api.compliance.reporting.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
sort	string Sort the list of results by a field.
type	string File type, either JSON or CSV.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"chef_organization": "string",
"chef_server": "string",
"chef_tags": ["string"
],
"controls": {"failed": {"critical": 0,
"major": 0,
"minor": 0,
"total": 0
},
"passed": {"total": 0
},
"skipped": {"total": 0
},
"total": 0,
"waived": {"total": 0
}
},
"end_time": "2019-08-24T14:15:22Z",
"environment": "string",
"fqdn": "string",
"id": "string",
"ipaddress": "string",
"job_id": "string",
"node_id": "string",
"node_name": "string",
"platform": {"full": "string",
"name": "string",
"release": "string"
},
"profiles": [{"attributes": [{"name": "string",
"options": {"default": "string",
"description": "string"
}
}
],
"controls": [{"code": "string",
"desc": "string",
"id": "string",
"impact": 0,
"refs": [{"ref": "string",
"url": "string"
}
],
"removed_results_counts": {"failed": 0,
"passed": 0,
"skipped": 0
},
"results": [{"code_desc": "string",
"message": "string",
"run_time": 0,
"skip_message": "string",
"start_time": "string",
"status": "string"
}
],
"source_location": {"line": 0,
"ref": "string"
},
"tags": "string",
"title": "string",
"waived_str": "string",
"waiver_data": {"expiration_date": "string",
"justification": "string",
"message": "string",
"run": true,
"skipped_due_to_waiver": true
}
}
],
"copyright": "string",
"copyright_email": "string",
"depends": [{"branch": "string",
"commit": "string",
"compliance": "string",
"git": "string",
"github": "string",
"name": "string",
"path": "string",
"skip_message": "string",
"status": "string",
"supermarket": "string",
"tag": "string",
"url": "string",
"version": "string"
}
],
"full": "string",
"groups": [{"controls": ["string"
],
"id": "string",
"title": "string"
}
],
"latest_version": "string",
"license": "string",
"maintainer": "string",
"name": "string",
"owner": "string",
"sha256": "string",
"skip_message": "string",
"status": "string",
"status_message": "string",
"summary": "string",
"supports": [{"inspec_version": "string",
"os_family": "string",
"os_name": "string",
"platform": "string",
"release": "string"
}
],
"title": "string",
"version": "string"
}
],
"projects": ["string"
],
"roles": ["string"
],
"statistics": {"duration": 0
},
"status": "string",
"status_message": "string",
"version": "string"
}

List Reporting Suggestions

Get suggestions for compliance reporting resources based on matching text substrings. Supports filtering, but not pagination or sorting. type parameter is required. It must be one of the parameters from the following table.

Suggestion type parameter	Suggestion type value
chef_server	source_fqdn
chef_tags	chef_tags
control	profiles.controls.title
control_tag_key	profiles.controls.string_tags.key
control_tag_value	profiles.controls.string_tags.values
environment	environment
inspec_version	version
node	node_name
organization	organization_name
platform	platform.name
platform_with_version	platform.full
policy_group	policy_group
policy_name	policy_name
profile	profiles.title
profile_with_version	profiles.full
recipe	recipes
role	roles

Example:

{
"type":"environment",
"text":"aws*",
"filters":[
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
]
}

Authorization Action:

compliance:reportSuggestions:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter) The criteria used to filter the suggestions returned.
size	integer <int32> The maximum number of suggestions to return.
text	string The term to use to match resources on.
type	string The type of resource to get suggestions for.
type_key	string The key (e.g. control_tag_key) to use for the type search.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"size": 0,
"text": "string",
"type": "string",
"type_key": "string"
}

Response samples

200
default

Content type

application/json

{"suggestions": [{"id": "string",
"score": 0,
"text": "string",
"version": "string"
}
]
}

Stats

Read Failures

Returns the top failures for the specified object. A types filter is required for this api. Supported values are platform, environment, control, and profile. By default, the top ten failed objects for the specified type are returned. Supports filtering and respects size parameter.

Example:

{
"filters":[
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]},
{"type":"types","values":["platform","environment"]}
]
}

Authorization Action:

compliance:reportFailures:get

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.stats.v1.ListFilter) Filters applied to the results.
id	string Unique identifier, such as a profile ID.
interval	integer <int32> The interval to use for ReadTrend results, in integer seconds. Default of one hour, 3600.
order	string (chef.automate.api.compliance.reporting.stats.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to fetch the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
size	integer <int32> The number of results to return (used when pagination is not supported).
sort	string Sort the list of results by a field.
type	string Type of data being requested, used for ReadTrend and ReadSummary.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"interval": 0,
"order": "ASC",
"page": 0,
"per_page": 0,
"size": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"controls": [{"failures": 0,
"id": "string",
"name": "string",
"profile": "string"
}
],
"environments": [{"failures": 0,
"id": "string",
"name": "string",
"profile": "string"
}
],
"platforms": [{"failures": 0,
"id": "string",
"name": "string",
"profile": "string"
}
],
"profiles": [{"failures": 0,
"id": "string",
"name": "string",
"profile": "string"
}
]
}

GetNodesUsageCount

Returns the count of unique nodes with lastRun in a given time. The time duration can be between the last time Telemetry data sent and the day before the current date. If the duration < 15 days --> 15 days duration > 15 days --> duration

Authorization Action:

iam:introspect:getAll

Responses

Response samples

200
default

Content type

application/json

{"days_since_last_post": "string",
"node_cnt": "string"
}

UpdateTelemetryReported

Acknowledge API to updates the last complaince telemetry reported date in postgres

Authorization Action:

iam:introspect:getAll

Request Body schema: application/json
required

last_telemetry_reported_at

string (last complaince telemetry reported date)

Responses

Request samples

Payload

Content type

application/json

{"last_telemetry_reported_at": "string"
}

Response samples

200
default

Content type

application/json

{ }

Read Profiles

Returns statistics and summary information for profiles executed as part of the compliance reports. If called without specifying a profile ID (id), the API will return stats on all the profiles. If the id field is provided (profile ID) as part of the query object, the type field must also be specified. Options are controls or summary. Supports filtering.

{
"type":"controls",
"id":"09adcbb3b9b3233d5de63cd98a5ba3e155b3aaeb66b5abed379f5fb1ff143988",
"filters":[
{"type":"environment","values":["dev*"]},
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
]
}

Authorization Action:

compliance:reportProfiles:get

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.stats.v1.ListFilter) Filters applied to the results.
id	string Unique identifier, such as a profile ID.
interval	integer <int32> The interval to use for ReadTrend results, in integer seconds. Default of one hour, 3600.
order	string (chef.automate.api.compliance.reporting.stats.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to fetch the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
size	integer <int32> The number of results to return (used when pagination is not supported).
sort	string Sort the list of results by a field.
type	string Type of data being requested, used for ReadTrend and ReadSummary.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"interval": 0,
"order": "ASC",
"page": 0,
"per_page": 0,
"size": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"control_stats": [{"control": "string",
"failed": 0,
"impact": 0,
"passed": 0,
"skipped": 0,
"title": "string",
"waived": 0
}
],
"profile_list": [{"criticals": 0,
"failures": 0,
"id": "string",
"majors": 0,
"minors": 0,
"name": "string",
"passed": 0,
"skipped": 0,
"waived": 0
}
],
"profile_summary": {"copyright": "string",
"copyright_email": "string",
"depends": [{"branch": "string",
"commit": "string",
"compliance": "string",
"git": "string",
"github": "string",
"name": "string",
"path": "string",
"skip_message": "string",
"status": "string",
"supermarket": "string",
"tag": "string",
"url": "string",
"version": "string"
}
],
"license": "string",
"maintainer": "string",
"name": "string",
"stats": {"failed": 0,
"failed_nodes": 0,
"passed": 0,
"skipped": 0,
"total_nodes": 0,
"waived": 0
},
"summary": "string",
"supports": [{"inspec_version": "string",
"os_family": "string",
"os_name": "string",
"platform": "string",
"platform_family": "string",
"platform_name": "string",
"release": "string"
}
],
"title": "string",
"version": "string"
}
}

Read Summary

Returns summary statistics for compliance reports. General report summary information is the default. Adding a type value of nodes or controls will return summary statistics for that object. Supports filtering.

The API supports date range filters when end_time is the current time and start_time is any time in last 90 days. In case, the end_time is any date other than the current date, the API would return data only for the end_time.

Example:

{
"type":"nodes",
"filters":[
{"type":"environment","values":["dev*"]},
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
]
}

Authorization Action:

compliance:reportSummary:get

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.stats.v1.ListFilter) Filters applied to the results.
id	string Unique identifier, such as a profile ID.
interval	integer <int32> The interval to use for ReadTrend results, in integer seconds. Default of one hour, 3600.
order	string (chef.automate.api.compliance.reporting.stats.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to fetch the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
size	integer <int32> The number of results to return (used when pagination is not supported).
sort	string Sort the list of results by a field.
type	string Type of data being requested, used for ReadTrend and ReadSummary.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"interval": 0,
"order": "ASC",
"page": 0,
"per_page": 0,
"size": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"controls_summary": {"criticals": 0,
"failures": 0,
"majors": 0,
"minors": 0,
"passed": 0,
"skipped": 0,
"waived": 0
},
"node_summary": {"compliant": 0,
"high_risk": 0,
"low_risk": 0,
"medium_risk": 0,
"noncompliant": 0,
"skipped": 0,
"waived": 0
},
"report_summary": {"duration": 0,
"start_date": "string",
"stats": {"controls": 0,
"environments": 0,
"nodes": "string",
"nodes_cnt": 0,
"platforms": 0,
"profiles": 0
},
"status": "string"
}
}

Read Trend

Returns trendgraph statistics for compliance reports. The type field is required for this api call. Options are nodes or controls. Requires minimum interval field of 3600 and defined start time and end time filters. Supports filtering.

Example:

{
"type":"nodes",
"interval":86400,
"filters":[
{"type":"environment","values":["dev*"]},
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
]
}

Authorization Action:

compliance:reportTrend:get

Request Body schema: application/json
required

	Array of objects (chef.automate.api.compliance.reporting.stats.v1.ListFilter) Filters applied to the results.
id	string Unique identifier, such as a profile ID.
interval	integer <int32> The interval to use for ReadTrend results, in integer seconds. Default of one hour, 3600.
order	string (chef.automate.api.compliance.reporting.stats.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to fetch the next page of the results.
per_page	integer <int32> The number of results on each paginated request page.
size	integer <int32> The number of results to return (used when pagination is not supported).
sort	string Sort the list of results by a field.
type	string Type of data being requested, used for ReadTrend and ReadSummary.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"id": "string",
"interval": 0,
"order": "ASC",
"page": 0,
"per_page": 0,
"size": 0,
"sort": "string",
"type": "string"
}

Response samples

200
default

Content type

application/json

{"trends": [{"failed": 0,
"passed": 0,
"report_time": "string",
"skipped": 0,
"waived": 0
}
]
}

Scan Jobs

Create a scan job

Creates a scan job. A scan job executes Chef InSpec against the specified nodes. Requires a user-specified name. Type should be detect (checks if the node is reachable and reports the platform information for the nodes) or exec (executes a set of profiles against the nodes). Nodes to scan may be specified by including an array of node IDs to scan or a node manager ID along with some optional filtering information. Exec jobs require at least one profile to be used as part of the Chef InSpec scan. Optional recurrence schedules enable regularly scheduled (repeating) scans.

Example:

{  
"name": "my testjob",
"tags": [],
"type": "exec",
"nodes": ["i07uc612-7e97-43f2-9b19-256abh785820"],
"profiles": ["https://github.com/dev-sec/linux-baseline/archive/master.tar.gz", "compliance://admin/ssh-baseline#2.2.0"],
"retries": 1,
"node_selectors":[
{
"manager_id":"e69dc612-7e67-43f2-9b19-256afd385820",
"filters":[{"key":"name","values":["ins*"],"exclude":false}]
}
],
"recurrence":"DTSTART=20191231T045100Z;FREQ=DAILY;INTERVAL=1"
}

Authorization Action:

compliance:scannerJobs:create

Request Body schema: application/json
required

deleted	boolean <boolean> Boolean used to denote the job has been marked as "deleted" by the user.
end_time	string <date-time> End time of the scan job, assigned by the service.
id	string Unique ID (UUID) of the scan job.
job_count	integer <int32> Count of scans executed by the job.
name	string User-specified name of the scan job.
node_count	integer <int32> Count of nodes to be scanned as part of the job, assigned by the service.
	Array of objects (chef.automate.api.compliance.scanner.jobs.v1.ManagerFilter) Set of node manager IDs and filters to associate with the scan job.
nodes	Array of strings List of node IDs to associate with the scan job.
parent_id	string ID of parent job to associate with the job, if any.
profile_count	integer <int32> Count of profiles to be executed as part of the job.
profiles	Array of strings List of profiles to execute as part of the scan job.
recurrence	string Recurrence schedule string for the job.
	Array of objects (chef.automate.api.compliance.scanner.jobs.v1.ResultsRow) Results of the scan job, including a report ID if one was generated.
retries	integer <int32> Number of times to retry the scan job. Default: 3.
retries_left	integer <int32> Number of retries left, assigned by the service.
scheduled_time	string <date-time> Next scheduled scan execution time.
start_time	string <date-time> Start time of the scan job, assigned by the service.
status	string Status of the scan job, assigned by the service.
	Array of objects (chef.automate.api.common.query.Kv) Tags to assign to the scan job.
timeout	integer <int32> Desired timeout (in seconds) for the scan job execution. Default: 7200 for exec jobs, 600 for detect jobs.
type	string Determines the type of Chef InSpec run, `detect` or `exec`.

Responses

Request samples

Payload

Content type

application/json

{"deleted": true,
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"job_count": 0,
"name": "string",
"node_count": 0,
"node_selectors": [{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"manager_id": "string"
}
],
"nodes": ["string"
],
"parent_id": "string",
"profile_count": 0,
"profiles": ["string"
],
"recurrence": "string",
"results": [{"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
}
],
"retries": 0,
"retries_left": 0,
"scheduled_time": "2019-08-24T14:15:22Z",
"start_time": "2019-08-24T14:15:22Z",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeout": 0,
"type": "string"
}

Response samples

200
default

Content type

application/json

{"id": "string",
"name": "string"
}

Read a scan job

Read the details of a scan job given an ID.

Authorization Action:

compliance:scannerJobs:get

path Parameters

id

required

string

Unique ID (UUID) assigned to object.

query Parameters

name	string Name of object.

Responses

Response samples

200
default

Content type

application/json

{"deleted": true,
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"job_count": 0,
"name": "string",
"node_count": 0,
"node_selectors": [{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"manager_id": "string"
}
],
"nodes": ["string"
],
"parent_id": "string",
"profile_count": 0,
"profiles": ["string"
],
"recurrence": "string",
"results": [{"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
}
],
"retries": 0,
"retries_left": 0,
"scheduled_time": "2019-08-24T14:15:22Z",
"start_time": "2019-08-24T14:15:22Z",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeout": 0,
"type": "string"
}

Update a job

PUT operation to update the details for a scan job, such as the name, profiles, node set, or recurrence schedule. Please note that this is a PUT operation, so all scan job details included in the create function should be included in the PUT message to update.

Authorization Action:

compliance:scannerJobs:update

path Parameters

id

required

string

Unique ID (UUID) of the scan job.

Request Body schema: application/json
required

deleted	boolean <boolean> Boolean used to denote the job has been marked as "deleted" by the user.
end_time	string <date-time> End time of the scan job, assigned by the service.
id	string Unique ID (UUID) of the scan job.
job_count	integer <int32> Count of scans executed by the job.
name	string User-specified name of the scan job.
node_count	integer <int32> Count of nodes to be scanned as part of the job, assigned by the service.
	Array of objects (chef.automate.api.compliance.scanner.jobs.v1.ManagerFilter) Set of node manager IDs and filters to associate with the scan job.
nodes	Array of strings List of node IDs to associate with the scan job.
parent_id	string ID of parent job to associate with the job, if any.
profile_count	integer <int32> Count of profiles to be executed as part of the job.
profiles	Array of strings List of profiles to execute as part of the scan job.
recurrence	string Recurrence schedule string for the job.
	Array of objects (chef.automate.api.compliance.scanner.jobs.v1.ResultsRow) Results of the scan job, including a report ID if one was generated.
retries	integer <int32> Number of times to retry the scan job. Default: 3.
retries_left	integer <int32> Number of retries left, assigned by the service.
scheduled_time	string <date-time> Next scheduled scan execution time.
start_time	string <date-time> Start time of the scan job, assigned by the service.
status	string Status of the scan job, assigned by the service.
	Array of objects (chef.automate.api.common.query.Kv) Tags to assign to the scan job.
timeout	integer <int32> Desired timeout (in seconds) for the scan job execution. Default: 7200 for exec jobs, 600 for detect jobs.
type	string Determines the type of Chef InSpec run, `detect` or `exec`.

Responses

Request samples

Payload

Content type

application/json

{"deleted": true,
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"job_count": 0,
"name": "string",
"node_count": 0,
"node_selectors": [{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"manager_id": "string"
}
],
"nodes": ["string"
],
"parent_id": "string",
"profile_count": 0,
"profiles": ["string"
],
"recurrence": "string",
"results": [{"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
}
],
"retries": 0,
"retries_left": 0,
"scheduled_time": "2019-08-24T14:15:22Z",
"start_time": "2019-08-24T14:15:22Z",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeout": 0,
"type": "string"
}

Response samples

200
default

Content type

application/json

null

Delete a scan job

Delete a scan job given an ID. Note this does not delete the report(s) generated by the scan job.

Authorization Action:

compliance:scannerJobs:delete

path Parameters

id

required

string

Unique ID (UUID) assigned to object.

query Parameters

name	string Name of object.

Responses

Response samples

200
default

Content type

application/json

null

Rerun a scan job

Does not create a new job in the database. Reads the job info given the job ID and runs a scan. The latest job information is then updated to reflect this latest run.

Authorization Action:

compliance:scannerJobs:rerun

path Parameters

id

required

string

Unique ID (UUID) assigned to object.

query Parameters

name	string Name of object.

Responses

Response samples

200
default

Content type

application/json

{ }

List of scan jobs

Returns a list of scan jobs matching the query. Supports filtering, sorting, and pagination. Valid filtering fields: job_type, parent_job, status Valid sorting fields: name, type, status, start_time, end_time

Example:

{
"filters":[
{"key":"job_type","values":["exec"]},
{"key":"parent_job","values":[""]}
],
"page":1,
"per_page":100,
"sort":"end_time",
"order":"DESC"
}

Authorization Action:

compliance:scannerJobs:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Filter) Use filters to limit the set of items returned.
order	string (chef.automate.api.compliance.scanner.jobs.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Return the results in ascending or descending order.
page	integer <int32> Starting page for the results.
per_page	integer <int32> The number of results on each page.
sort	string Sort the results on a specific field.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string"
}

Response samples

200
default

Content type

application/json

{"jobs": [{"deleted": true,
"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"job_count": 0,
"name": "string",
"node_count": 0,
"node_selectors": [{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"manager_id": "string"
}
],
"nodes": ["string"
],
"parent_id": "string",
"profile_count": 0,
"profiles": ["string"
],
"recurrence": "string",
"results": [{"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
}
],
"retries": 0,
"retries_left": 0,
"scheduled_time": "2019-08-24T14:15:22Z",
"start_time": "2019-08-24T14:15:22Z",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeout": 0,
"type": "string"
}
],
"total": 0
}

Profiles

Show an available profile

Show the details of an un-installed profile using the profile name and version. in the UI, these are the profiles under the "Available" tab. These profiles are created and maintained by Chef, shipped with Chef Automate.

Authorization Action:

compliance:marketProfiles:get

path Parameters

name required	string Name of the profile.
version required	string Version of the profile.

query Parameters

owner

string

Automate user associated with the profile.

Responses

Response samples

200
default

Content type

application/json

{"attributes": [{"name": "string",
"options": {"default": "string",
"description": "string"
}
}
],
"controls": [{"code": "string",
"desc": "string",
"id": "string",
"impact": 0,
"refs": [{"ref": "string",
"url": "string"
}
],
"results": [{"code_desc": "string",
"message": "string",
"run_time": 0,
"skip_message": "string",
"start_time": "string",
"status": "string"
}
],
"source_location": {"line": 0,
"ref": "string"
},
"tags": {"property1": "string",
"property2": "string"
},
"title": "string"
}
],
"copyright": "string",
"copyright_email": "string",
"depends": [{"branch": "string",
"commit": "string",
"compliance": "string",
"git": "string",
"github": "string",
"name": "string",
"path": "string",
"supermarket": "string",
"tag": "string",
"url": "string",
"version": "string"
}
],
"groups": [{"controls": ["string"
],
"id": "string",
"title": "string"
}
],
"latest_version": "string",
"license": "string",
"maintainer": "string",
"name": "string",
"owner": "string",
"sha256": "string",
"summary": "string",
"supports": [{"inspec_version": "string",
"os_family": "string",
"os_name": "string",
"platform": "string",
"release": "string"
}
],
"title": "string",
"version": "string"
}

Upload a Profile

Upload a profile to Chef Automate. This can be a tarball or zip of the profile, or a reference to one of the market profiles.

Example:

api/v0/compliance/profiles?owner=admin -d '{"name":"cis-amazonlinux-2014.09-2015.03-level2","version":"1.1.0-5"}'

Example:

-F file=@/path-to-local-file/linux-baseline-2.0.0.zip api/v0compliance/profiles?contentType=application/x-gzip&owner=admin

Authorization Action: compliance:profiles:create

Request Body schema: application/json
required

chunk	any Profile contents in byte form.
meta	any Profile metadata.
owner	string Associate a Chef Automate user with a profile. A profile is visible only to its associated user.

Responses

Request samples

Payload

Content type

application/json

{"chunk": null,
"meta": null,
"owner": "string"
}

Response samples

200

Content type

application/json

{"errors": [{"column": 0,
"control_id": "string",
"file": "string",
"line": 0,
"msg": "string"
}
],
"summary": {"controls": 0,
"location": "string",
"timestamp": "string",
"valid": true
},
"warnings": [{"column": 0,
"control_id": "string",
"file": "string",
"line": 0,
"msg": "string"
}
]
}

Check if one or multiple profiles exist in the metadata database.

The endpoint takes an array of compliance profile sha256 IDs and returns the ones that the backend doesn't have metadata (profile title, copyright, controls title, code, tags, etc) for. This is useful when deciding if a compliance report can be sent for ingestion without the associated profile metadata.

Authorization Action:

compliance:profiles:list

Request Body schema: application/json
required

sha256

Array of strings

An array of profile sha256 IDs.

Responses

Request samples

Payload

Content type

application/json

{"sha256": ["string"
]
}

Response samples

200
default

Content type

application/json

{"missing_sha256": ["string"
]
}

Show an installed profile

Show the details of an installed profile given the profile name, owner (Automate user associated with the profile), and version.

Authorization Action:

compliance:profiles:get

path Parameters

owner required	string Automate user associated with the profile.
name required	string Name of the profile.
version required	string Version of the profile.

Responses

Response samples

200
default

Content type

application/json

{"attributes": [{"name": "string",
"options": {"default": "string",
"description": "string"
}
}
],
"controls": [{"code": "string",
"desc": "string",
"id": "string",
"impact": 0,
"refs": [{"ref": "string",
"url": "string"
}
],
"results": [{"code_desc": "string",
"message": "string",
"run_time": 0,
"skip_message": "string",
"start_time": "string",
"status": "string"
}
],
"source_location": {"line": 0,
"ref": "string"
},
"tags": {"property1": "string",
"property2": "string"
},
"title": "string"
}
],
"copyright": "string",
"copyright_email": "string",
"depends": [{"branch": "string",
"commit": "string",
"compliance": "string",
"git": "string",
"github": "string",
"name": "string",
"path": "string",
"supermarket": "string",
"tag": "string",
"url": "string",
"version": "string"
}
],
"groups": [{"controls": ["string"
],
"id": "string",
"title": "string"
}
],
"latest_version": "string",
"license": "string",
"maintainer": "string",
"name": "string",
"owner": "string",
"sha256": "string",
"summary": "string",
"supports": [{"inspec_version": "string",
"os_family": "string",
"os_name": "string",
"platform": "string",
"release": "string"
}
],
"title": "string",
"version": "string"
}

List all available profiles

Lists all profiles available for the Automate instance. Empty params return all "market" profiles. Specifying the owner field returns all profiles installed for the specified user.

Supports pagination, sorting, and filtering (wildcard supported).

Supported sort fields: title, name (default: title) Supported filter fields: name, version, title

Example:

{
"filters":[
{"type": "title", "values": [ "Dev*"]}
],
"page": 1,
"per_page": 3,
"owner": "admin"
}

Authorization Action:

compliance:profiles:list

Request Body schema: application/json
required

	Array of objects (Filters to apply to the query)
name	string Name of the profile (as defined in `inspec.yml`).
order	string (chef.automate.api.compliance.profiles.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC"
owner	string Automate user associated with the profile.
page	integer <int32> Page of results requested.
per_page	integer <int32> Number of results to return per page.
sort	string Field on which to sort.
version	string Version of the profile (as defined in `inspec.yml`).

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
],
"name": "string",
"order": "ASC",
"owner": "string",
"page": 0,
"per_page": 0,
"sort": "string",
"version": "string"
}

Response samples

200
default

Content type

application/json

{"profiles": [{"attributes": [{"name": "string",
"options": {"default": "string",
"description": "string"
}
}
],
"controls": [{"code": "string",
"desc": "string",
"id": "string",
"impact": 0,
"refs": [{"ref": "string",
"url": "string"
}
],
"results": [{"code_desc": "string",
"message": "string",
"run_time": 0,
"skip_message": "string",
"start_time": "string",
"status": "string"
}
],
"source_location": {"line": 0,
"ref": "string"
},
"tags": {"property1": "string",
"property2": "string"
},
"title": "string"
}
],
"copyright": "string",
"copyright_email": "string",
"depends": [{"branch": "string",
"commit": "string",
"compliance": "string",
"git": "string",
"github": "string",
"name": "string",
"path": "string",
"supermarket": "string",
"tag": "string",
"url": "string",
"version": "string"
}
],
"groups": [{"controls": ["string"
],
"id": "string",
"title": "string"
}
],
"latest_version": "string",
"license": "string",
"maintainer": "string",
"name": "string",
"owner": "string",
"sha256": "string",
"summary": "string",
"supports": [{"inspec_version": "string",
"os_family": "string",
"os_name": "string",
"platform": "string",
"release": "string"
}
],
"title": "string",
"version": "string"
}
],
"total": 0
}

Download a Profile

Download a profile in tarball form. The profile will be downloaded to the user's local workstation.

Example:

{"name":"cis-amazonlinux2-level1","version":"1.0.0-5"}'

Authorization Action: compliance:profiles:get compliance:marketProfiles:get

Request Body schema: application/json
required

data	bytes Profile contents in byte form.
name	string Profile name.
owner	string Chef Automate user associated with the profile.
version	string Profile version.

Responses

Request samples

Payload

Content type

application/json

{"data": null,
"name": "string",
"owner": "string",
"version": "string"
}

Response samples

200

Content type

application/json

{"data": "string",
"name": "string",
"owner": "string",
"version": "string"
}

Delete an installed profile

Delete an installed profile given the profile name, owner (Automate user associated with the profile), and version. Note: this action "uninstalls" the profile. This has no impact on the market profiles.

Authorization Action:

compliance:profiles:delete

path Parameters

owner required	string Automate user associated with the profile.
name required	string Name of the profile.
version required	string Version of the profile.

Responses

Response samples

200
default

Content type

application/json

null

Assets Management

Set Unreachable Assets Config

SetAssetConfig sets the compliance config with the parameters of no of days And API returns the policy name and no of the days which will set in the compliance data base

Authorization Action:

compliance:reports:update

Request Body schema: application/json
required

value

integer <int32> (No of days for the config)

Responses

Request samples

Payload

Content type

application/json

{"value": 0
}

Response samples

200
default

Content type

application/json

{"policy_name": "string",
"value": 0
}

Get Assets Config

GetAssetConfig gets the config details from the compliance data base and API return the policy name and no of days Authorization Action:

compliance:reports:get

Responses

Response samples

200
default

Content type

application/json

{"policy_name": "string",
"value": 0
}

Assets Count

Count the compliance assets based on different filter options. The API returns the response based on reported and unreported assets

Authorization Action:

compliance:reports:list

Request Body schema: application/json
required

Array of objects (chef.automate.api.compliance.reporting.v1.ListFilter)

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"type": "string",
"values": ["string"
]
}
]
}

Response samples

200
default

Content type

application/json

{"collected": {"failed": 0,
"passed": 0,
"skipped": 0,
"waived": 0
},
"total_assets": 0,
"uncollected": {"unreachable": 0,
"unreported": 0
}
}

List Assets

Lists the compliance assets based on different filter options. The API works with filtering assets based on collected, uncollected, unreported and unreachable assets

Authorization Action:

compliance:reports:list

Request Body schema: application/json
required

assets_type	string (Asset Type as collected, unreported, unreachable, uncollected)
	Array of objects (List of the filters to be applied)
from	integer <int32> The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results.
size	integer <int32> (Size of the asset list)
sort	string (Sort required from the which field)

Responses

Request samples

Payload

Content type

application/json

{"assets_type": "string",
"filters": [{"type": "string",
"values": ["string"
]
}
],
"from": 0,
"size": 0,
"sort": "string"
}

Response samples

200
default

Content type

application/json

{"assets": [{"first_run": "string",
"last_run": "string",
"node_uuid": "string",
"status": "string"
}
]
}

Report Manager

List Download Report Requests

Returns the details of the download report requests placed by the user.

Authorization Action:

reportmanager:requests:list

Responses

Response samples

200
default

Content type

application/json

{"data": [{"acknowledgement_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"duration": "string",
"ended_at": "2019-08-24T14:15:22Z",
"err_message": "string",
"report_size": "string",
"report_type": "string",
"status": "string"
}
]
}

Nodes

CreateRollout

Creates a Rollout record. A rollout represents the process of nodes acquiring the latest policy revision pushed to a policy group.

Authorization Action:

ingest:unifiedEvents:create

Request Body schema: application/json
required

ci_job_id	string
ci_job_url	string
description	string
policy_domain_url	string
policy_domain_username	string
policy_name	string
policy_node_group	string
policy_revision_id	string
policy_scm_commit	string
policy_scm_url	string
policy_scm_web_url	string
scm_author_email	string
scm_author_name	string
scm_type	string (chef.automate.api.cfgmgmt.request.SCMType) Default: "SCM_TYPE_UNSPECIFIED" Enum: "SCM_TYPE_UNSPECIFIED" "SCM_TYPE_UNKNOWN_SCM" "SCM_TYPE_GIT"
scm_web_type	string (chef.automate.api.cfgmgmt.request.SCMWebType) Default: "SCM_WEB_TYPE_UNSPECIFIED" Enum: "SCM_WEB_TYPE_UNSPECIFIED" "SCM_WEB_TYPE_UNKNOWN_SCM_WEB" "SCM_WEB_TYPE_GITHUB"

Responses

Request samples

Payload

Content type

application/json

{"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED"
}

Response samples

200
default

Content type

application/json

{"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
}

GetRolloutForChefRun

Returns the rollout for the given Chef Server/org, policy group, policy name, and policy revision

Authorization Action:

infra:nodes:list

query Parameters

policy_name	string
policy_group	string
policy_revision_id	string

Responses

Response samples

200
default

Content type

application/json

{"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
}

GetRollouts

Gives a list of rollouts

Authorization Action:

infra:nodes:list

query Parameters

filter

Array of strings

Filters to apply to the request for the rollouts list.

Responses

Response samples

200
default

Content type

application/json

{"rollouts": [{"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
}
]
}

ConfigMgmt_ListNodeSegmentsWithRolloutProgress

query Parameters

filter

Array of strings

Filters to apply to the request for the node segments list.

Responses

Response samples

200
default

Content type

application/json

{"node_segment_rollout_progress": [{"current_rollout_progress": {"build_link": "string",
"latest_run_errored_count": 0,
"latest_run_successful_count": 0,
"node_count": 0,
"rollout": {"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
},
"source_link": "string"
},
"policy_domain_url": "string",
"policy_name": "string",
"policy_node_group": "string",
"previous_rollouts": [{"build_link": "string",
"latest_run_node_count": 0,
"rollout": {"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
},
"source_link": "string"
}
],
"total_nodes": 0
}
]
}

GetRolloutById

Returns the rollout with the given Id

Authorization Action:

infra:nodes:list

path Parameters

rollout_id

required

string

Responses

Response samples

200
default

Content type

application/json

{"ci_job_id": "string",
"ci_job_url": "string",
"description": "string",
"end_time": "string",
"id": "string",
"policy_domain_url": "string",
"policy_domain_username": "string",
"policy_name": "string",
"policy_node_group": "string",
"policy_revision_id": "string",
"policy_scm_commit": "string",
"policy_scm_url": "string",
"policy_scm_web_url": "string",
"scm_author_email": "string",
"scm_author_name": "string",
"scm_type": "SCM_TYPE_UNSPECIFIED",
"scm_web_type": "SCM_WEB_TYPE_UNSPECIFIED",
"start_time": "string"
}

CreateRolloutTest

CreateRolloutTest is a no-op endpoint that has the same auth requirements as CreateRollout. It can be used to verify end-to-end config/connectivity for clients

Authorization Action:

ingest:unifiedEvents:create

Request Body schema: application/json
required

object (chef.automate.api.cfgmgmt.request.CreateRolloutTest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{ }

List Errors

Returns a list of the most common errors reported for infra nodes' most recent Chef Infra Client runs.

Authorization Action:

infra:nodes:list

query Parameters

size	integer <int32> The number of results to return. If set to zero, the default size of 10 will be used. Set to a negative value for unlimited results.
filter	Array of strings Filters in the request select the nodes from which the errors are collected. The same filters may be specified for this request as for other Nodes requests, with the exception of 'status' which is not valid for this request.

Responses

Response samples

200
default

Content type

application/json

{"errors": [{"count": 0,
"error_message": "string",
"type": "string"
}
]
}

GetNodeMetadataCounts

For each type of field requested this returns distinct values the amount of each. For example, if the 'platform' field is requested 'windows' 10, 'redhat' 5, and 'ubuntu' 8 could be returned. The number next to each represents the number of nodes with that type of platform.

Example: request

cfgmgmt/node_metadata_counts?type=platform&type=status

response

{
"types": [
{
"values": [
{
"value": "mac_os_x 10.11.5",
"count": 28
},
{
"value": "linux 8.9",
"count": 1
},
{
"value": "macos 8.9",
"count": 1
},
{
"value": "windows 8.9",
"count": 1
}
],
"type": "platform"
},
{
"value": [
{
"value": "missing",
"count": 29
},
{
"value": "failure",
"count": 2
}
],
"type": "status"
}
]
}

Authorization Action:

infra:nodes:list

query Parameters

type	Array of strings Types of node fields to collect value counts for.
filter	Array of strings Filters to apply to the counts returned.
start	string Earliest most recent check-in node information to return.
end	string Latest most recent check-in node information to return.

Responses

Response samples

200
default

Content type

application/json

{"types": [{"type": "string",
"values": [{"count": 0,
"value": "string"
}
]
}
]
}

GetNodeRunsDailyStatusTimeSeries

Provides the status of runs for each 24-hour duration. For multiple runs in one 24-hour duration, the most recent failed run will be returned. If there are no failed runs the most recent successful run will be returned. If no runs are found in the 24-hour duration, the status will be "missing" and no run information will be returned.

Example: request

cfgmgmt/node_runs_daily_status_time_series?node_id=507bd518-5c18-4c2d-a445-60fe7dde9961&days_ago=3

response

{
"durations": [
{
"start": "2020-04-25T19:00:00Z",
"end": "2020-04-26T18:59:59Z",
"status": "missing",
"run_id": ""
},
{
"start": "2020-04-26T19:00:00Z",
"end": "2020-04-27T18:59:59Z",
"status": "missing",
"run_id": ""
},
{
"start": "2020-04-27T19:00:00Z",
"end": "2020-04-28T18:59:59Z",
"status": "failure",
"run_id": "b7904f41-68b5-44ec-9da6-cf2481ff8600"
}
]
}

Authorization Action:

infra:nodes:list

query Parameters

node_id	string Node ID of the runs.
days_ago	integer <int32> Number of past days.

Responses

Response samples

200
default

Content type

application/json

{"durations": [{"end": "string",
"run_id": "string",
"start": "string",
"status": "string"
}
]
}

List Checked-in Nodes

Returns a list of infra nodes that have checked in to Automate. Adding a filter makes a list of all nodes that meet the filter criteria. Filters for the same field are ORd together, while filters across different fields are ANDed together. Supports pagination, filtering (with wildcard support), and sorting. Max return payload size is 4MB, use pagination to fetch remaining data.

Example:

cfgmgmt/nodes?pagination.page=1&pagination.size=100&sorting.field=name&sorting.order=ASC&filter=name:mySO*&filter=platform:ubun*

Authorization Action:

infra:nodes:list

query Parameters

filter	Array of strings Filters to apply to the request for nodes list.
pagination.page	integer <int32> Page number of the results to return.
pagination.size	integer <int32> Amount of results to include per page.
sorting.field	string Field to sort the list results on.
sorting.order	string Default: "ASC" Enum: "ASC" "DESC" Order the results should be returned in.
start	string Earliest most recent check-in node information to return.
end	string Latest most recent check-in node information to return.

Responses

Response samples

200
default

Content type

application/json

[{ }
]

NodeExport

Stream nodes in JSON (default) or CSV format.

Supports filtering and sorting, but not pagination.

Include the value csv for the output_type parameter in the request to receive CSV formatted data. Include the value json for the output_type parameter in the request to receive JSON formatted data. Include the value 0 to sort descending. Include the value 1 to sort ascending. Example:

'{"output_type":"csv","sorting":{"order": 1, "field": "name"},"filters":[{"status":"success","environment":"prod", "organization:chef"}]}'

Request Body schema: application/json
required

filter	Array of strings Filters to apply to the request for nodes list. May be empty.
output_type	string Default: "json" Enum: "json" "csv" File type, either JSON or CSV.
	object (chef.automate.api.common.query.Sorting)

Responses

Request samples

Payload

Content type

application/json

{"filter": ["string"
],
"output_type": "json",
"sorting": {"field": "string",
"order": "ASC"
}
}

Response samples

200

Content type

application/json

{"content": "string"
}

Show Attributes

Returns the latest reported attributes for the provided node ID.

Authorization Action:

infra:nodes:get

path Parameters

node_id

required

string

Chef guid for the requested node.

Responses

Response samples

200
default

Content type

application/json

{"all_value_count": 0,
"automatic": "string",
"automatic_value_count": 0,
"chef_environment": "string",
"default": "string",
"default_value_count": 0,
"name": "string",
"node_id": "string",
"normal": "string",
"normal_value_count": 0,
"override": "string",
"override_value_count": 0,
"run_list": ["string"
]
}

List Run Details

Returns a list of run metadata (id, start and end time, and status) for the provided node ID. Supports pagination. Accepts a start parameter to denote start date for the list and a filter of type status.

Authorization Action:

infra:nodes:list

path Parameters

node_id

required

string

Chef guid for the node.

query Parameters

filter	Array of strings Filters to apply to the request for runs list.
pagination.page	integer <int32> Page number of the results to return.
pagination.size	integer <int32> Amount of results to include per page.
start	string Earliest (in history) run information to return for the runs list.
end	string Latest (in history) run information to return for the runs list.

Responses

Response samples

200
default

Content type

application/json

[{ }
]

Show Node Run

Returns the infra run report for the provided node ID and run ID.

Authorization Action:

infra:nodes:get

path Parameters

node_id required	string Chef guid for the requested node.
run_id required	string Run id for the node.

query Parameters

end_time

string <date-time>

End time on the node's run.

Responses

Response samples

200
default

Content type

application/json

{"chef_tags": ["string"
],
"chef_version": "string",
"cloud_provider": "string",
"cookbooks": ["string"
],
"deprecations": [{"location": "string",
"message": "string",
"url": "string"
}
],
"dmi_system_manufacturer": "string",
"dmi_system_serial_number": "string",
"domain": "string",
"end_time": "2019-08-24T14:15:22Z",
"environment": "string",
"error": {"backtrace": ["string"
],
"class": "string",
"description": {"sections": [{ }
],
"title": "string"
},
"message": "string"
},
"expanded_run_list": {"id": "string",
"run_list": [{"children": [{ }
],
"name": "string",
"skipped": true,
"type": "string",
"version": "string"
}
]
},
"fqdn": "string",
"hostname": "string",
"id": "string",
"ip6address": "string",
"ipaddress": "string",
"kernel_release": "string",
"kernel_version": "string",
"macaddress": "string",
"memory_total": "string",
"node_id": "string",
"node_name": "string",
"organization": "string",
"platform": "string",
"platform_family": "string",
"platform_version": "string",
"policy_group": "string",
"policy_name": "string",
"policy_revision": "string",
"projects": ["string"
],
"recipes": ["string"
],
"resource_names": ["string"
],
"resources": [{"conditional": "string",
"cookbook_name": "string",
"cookbook_version": "string",
"delta": "string",
"duration": "string",
"error": {"backtrace": ["string"
],
"class": "string",
"description": {"sections": [{ }
],
"title": "string"
},
"message": "string"
},
"id": "string",
"ignore_failure": true,
"name": "string",
"recipe_name": "string",
"result": "string",
"status": "string",
"type": "string"
}
],
"roles": ["string"
],
"run_list": ["string"
],
"source": "string",
"source_fqdn": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string",
"tags": ["string"
],
"timezone": "string",
"total_resource_count": 0,
"updated_resource_count": 0,
"uptime_seconds": 0,
"versioned_cookbooks": [{"name": "string",
"version": "string"
}
],
"virtualization_role": "string",
"virtualization_system": "string"
}

List Organizations

Returns a list of all organizations associated with nodes that have checked in to Automate.

Authorization Action:

infra:nodes:list

Responses

Response samples

200
default

Content type

application/json

[{ }
]

List Policy Cookbooks

Returns Policy Names with a list of cookbook names and associated policy identifiers based on a policy revision ID. Policy revision IDs are sent with an infra run report and identifies which instance of a policy the node used for this run.

Authorization Action:

infra:nodes:list

path Parameters

revision_id

required

string

Revision id for the policy.

Responses

Response samples

200
default

Content type

application/json

{"cookbook_locks": [{"cookbook": "string",
"policy_identifier": "string"
}
],
"policy_name": "string"
}

ReportExport

Stream node run reports in JSON (default) or CSV format.

Supports filtering, but not pagination or sorting.

Include the value csv for the output_type parameter in the request to receive CSV formatted data. Include the value json for the output_type parameter in the request to receive JSON formatted data. Include the node ID for the node_id for the reports to receive. Include the number of seconds since the Unix Epoch for the start and end fields. Example:

'{"output_type":"csv"node_id":"80e73cf5-32eb-3556-ac99-6597274a8522","start":{"seconds":1585336095},"end":{"seconds":1585337095},"filters":[{"status":"success"}]}'

Request Body schema: application/json
required

end	string <date-time> Latest (in history) run information to return for the runs list. Not required.
filter	Array of strings Filters to apply to the request for nodes list. May be empty.
node_id	string The node ID of the reports. Required.
output_type	string Default: "json" Enum: "json" "csv" File type, either JSON or CSV.
start	string <date-time> Earliest (in history) run information to return for the runs list. Not required.

Responses

Request samples

Payload

Content type

application/json

{"end": "2019-08-24T14:15:22Z",
"filter": ["string"
],
"node_id": "string",
"output_type": "json",
"start": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json

{"content": "string"
}

List Associated Chef Infra Servers

Returns a list of all Chef Infra Servers associated with nodes that have checked in to Automate.

Authorization Action:

infra:nodes:list

Responses

Response samples

200
default

Content type

application/json

[{ }
]

List Node Checkins

Returns a daily time series of unique node check-ins for the number of days requested. If days ago value is empty, API will return the default 1 day ago results.

Authorization Action:

infra:nodes:list

query Parameters

filter	Array of strings List of filters to be applied to the time series.
days_ago	integer <int32> Number of past days to create the time series.

Responses

Response samples

200
default

Content type

application/json

{"counts": [{"count": 0,
"end": "string",
"start": "string",
"total": 0
}
]
}

List Missing Nodes Count

Returns a count of missing nodes for the provided durations.

Example:

cfgmgmt/stats/missing_node_duration_counts?durations=3d&durations=1w&durations=2w&durations=1M&durations=3M

Authorization Action:

infra:nodes:list

query Parameters

durations

Array of strings

A valid duration is any number zero or greater with one of these characters 'h', 'd', 'w', or 'M'. 'h' is hours 'd' is days 'w' is weeks 'M' is months Will contain one or many.

Responses

Response samples

200
default

Content type

application/json

{"counted_durations": [{"count": 0,
"duration": "string"
}
]
}

List Node Status Counts

Returns totals for failed, success, missing, and overall total infra nodes that have reported into Automate. Supports filtering.

Example:

cfgmgmt/stats/node_counts?filter=name:mySO*&filter=platform:ubun*

Authorization Action:

infra:nodes:list

query Parameters

filter	Array of strings List of filters to be applied to the node count results.
start	string Earliest node check-in.
end	string Latest node check-in.

Responses

Response samples

200
default

Content type

application/json

{"failure": 0,
"missing": 0,
"success": 0,
"total": 0
}

List Run Status Totals

Returns totals for failed and successful runs given a node_id.

Example:

cfgmgmt/stats/run_counts?node_id=821fff07-abc9-4160-96b1-83d68ae5cfdd&start=2019-11-02

Authorization Action:

infra:nodes:list

query Parameters

filter	Array of strings List of filters to be applied to the run count results.
start	string Earliest (in history) run information to return for the run counts.
end	string Latest (in history) run information to return for the run counts.
node_id	string Node id associated with the run.

Responses

Response samples

200
default

Content type

application/json

{"failure": 0,
"success": 0,
"total": 0
}

List Filter Suggestions

Returns possible filter values given a valid type parameter. All values returned until two or more characters are provided for the text parameter. Supports wildcard (* and ?).

Example:

cfgmgmt/suggestions?type=environment&text=_d

Authorization Action:

infra:nodes:list

query Parameters

type	string Field for which suggestions are being returned.
text	string Text to search on for the type value.
filter	Array of strings Filters to be applied to the results.

Responses

Response samples

200
default

Content type

application/json

[{ }
]

GetNodesUsageCount

Returns the count of unique nodes with lastRun in a given time. The time duration can be between the last time Telemetry data sent and the day before the current date. If the duration < 15 days --> 15 days duration > 15 days --> duration Authorization Action:

iam:introspect:getAll

Responses

Response samples

200
default

Content type

application/json

{"days_since_last_post": "string",
"node_cnt": "string"
}

UpdateTelemetryReported Acknowledge API to updates the last client run telemetry reported date in postgres Authorization Action: ``` iam:introspect:getAll ```

Request Body schema: application/json
required

last_telemetry_reported_at

string (last client run telemetry reported date)

Responses

Request samples

Payload

Content type

application/json

{"last_telemetry_reported_at": "string"
}

Response samples

200
default

Content type

application/json

{ }

Node Managers

Create a Node Manager

Creates a node manager given a name, credential id or credential data, and type.

Authorization Action:

infra:nodeManagers:create

Request Body schema: application/json
required

account_id	string Account id associated with the nodemanager.
required	Array of objects (chef.automate.api.common.query.Kv) Use either 'credential_data' OR 'credential_id'. 'credential_data' will overwrite values in 'credential_id'. Use 'credential_data' when you have not yet created node credentials and provide credential data (such as AWS_ACCESS_KEY) inline.
credential_id required	string Use either 'credential_id' OR 'credential_data'. 'credential_data' will overwrite values in 'credential_id'. The 'credential_id' is the UUID of credential with the information you need to connect to aws, azure, or gcp.
date_added	string <date-time> Date the nodemanager was created.
id required	string UUID for the nodemanager.
	Array of objects (chef.automate.api.nodes.manager.v1.CredentialsByTags) List of tag and credential UUID associations for making node managers. These are ssh, winrm, and sudo creds used to access instances.
name	string User defined name for the node manager.
status	string Status of the nodemanager (reachable, unreachable).
type required	string Type of nodemanager (aws-ec2, azure-vm, aws-api, azure-api, gcp).

Responses

Request samples

Payload

Content type

application/json

{"account_id": "12345EXAMPLE",
"credential_ID": "my-credential-UUID",
"credential_data": [{"key": "AWS_ACCESS_KEY_ID",
"value": "AKIAIOSFODNN7EXAMPLE"
},
{"key": "AWS_SECRET_ACCESS_KEY",
"value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
{"key": "AWS_SESSION_TOKEN",
"value": "AQoDYXdzEPT//////////wEXAMPLEt=="
}
],
"id": "cd3ad3d9-2776-4ef1-a904-1EXAMPLEUUID",
"instance_credentials": [ ],
"name": "my aws api integration with session token",
"type": "aws-ec2"
}

Response samples

200
default

Content type

application/json

{"ids": [{"uuid": "cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
}
]
}

View a Node Manager

List the details of a node manager.

Authorization Action:

infra:nodeManagers:get

path Parameters

id

required

string

UUID for the node manager.

Responses

Response samples

200
default

Content type

application/json

{"account_id": "12345EXAMPLE",
"credential_ID": "my-credential-UUID",
"credential_data": [{"key": "AWS_ACCESS_KEY_ID",
"value": "AKIAIOSFODNN7EXAMPLE"
},
{"key": "AWS_SECRET_ACCESS_KEY",
"value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
{"key": "AWS_SESSION_TOKEN",
"value": "AQoDYXdzEPT//////////wEXAMPLEt=="
}
],
"id": "cd3ad3d9-2776-4ef1-a904-1EXAMPLEUUID",
"instance_credentials": [ ],
"name": "my aws api integration with session token",
"type": "aws-ec2"
}

Update a Node Manager

Update a node manager's metadata, such as its name, associated credential id, or data. This is a PUT operation and it overwrites ALL of the existing node manager metadata. Include all fields, because a PUT operation overwrites any missing fields to empty ("").

Authorization Action:

infra:nodeManagers:update

path Parameters

id

required

string

UUID for the nodemanager.

Request Body schema: application/json
required

account_id	string Account id associated with the nodemanager.
required	Array of objects (chef.automate.api.common.query.Kv) Use either 'credential_data' OR 'credential_id'. 'credential_data' will overwrite values in 'credential_id'. Use 'credential_data' when you have not yet created node credentials and provide credential data (such as AWS_ACCESS_KEY) inline.
credential_id required	string Use either 'credential_id' OR 'credential_data'. 'credential_data' will overwrite values in 'credential_id'. The 'credential_id' is the UUID of credential with the information you need to connect to aws, azure, or gcp.
date_added	string <date-time> Date the nodemanager was created.
id required	string UUID for the nodemanager.
	Array of objects (chef.automate.api.nodes.manager.v1.CredentialsByTags) List of tag and credential UUID associations for making node managers. These are ssh, winrm, and sudo creds used to access instances.
name	string User defined name for the node manager.
status	string Status of the nodemanager (reachable, unreachable).
type required	string Type of nodemanager (aws-ec2, azure-vm, aws-api, azure-api, gcp).

Responses

Request samples

Payload

Content type

application/json

{"account_id": "12345EXAMPLE",
"credential_ID": "my-credential-UUID",
"credential_data": [{"key": "AWS_ACCESS_KEY_ID",
"value": "AKIAIOSFODNN7EXAMPLE"
},
{"key": "AWS_SECRET_ACCESS_KEY",
"value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
{"key": "AWS_SESSION_TOKEN",
"value": "AQoDYXdzEPT//////////wEXAMPLEt=="
}
],
"id": "cd3ad3d9-2776-4ef1-a904-1EXAMPLEUUID",
"instance_credentials": [ ],
"name": "my aws api integration with session token",
"type": "aws-ec2"
}

Response samples

200
default

Content type

application/json

null

Delete a Node Manager

Delete a single node manager. This deletes the node manager itself and reassigns its associated nodes to the Automate node manager.

Authorization Action:

infra:nodeManagers:delete

path Parameters

id

required

string

UUID for the node manager.

Responses

Response samples

200
default

Content type

application/json

null

Delete a Node Manager and Stop Nodes

Delete a node manager and update its associated nodes to stopped.

Authorization Action:

infra:nodeManagers:delete

path Parameters

id

required

string

UUID for the node manager.

Responses

Response samples

200
default

Content type

application/json

null

Delete a Node Manager and Terminate Nodes

Delete a node manager and update its associated nodes to terminated.

Authorization Action:

infra:nodeManagers:delete

path Parameters

id

required

string

UUID for the node manager.

Responses

Response samples

200
default

Content type

application/json

null

Delete a Node Manager and Delete Nodes

Delete a node manager and all of its associated nodes.

Authorization Action:

infra:nodeManagers:delete

path Parameters

id

required

string

UUID for the node manager.

Responses

Response samples

200
default

Content type

application/json

{"ids": [{"uuid": "cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
}
]
}

Search Node Fields

Searches the available values for a given field across all nodes associated with the nodemanager id.

Authorization Action:

infra:nodeManagers:list

path Parameters

node_manager_id

required

string

Node manager ID.

Request Body schema: application/json
required

field	string Possible search fields: regions, tags, name, subscription_id.
node_manager_id required	string Node manager ID.
	object (chef.automate.api.nodes.manager.v1.Query)

Responses

Request samples

Payload

Content type

application/json

{"field": "string",
"node_manager_id": "string",
"query": {"filter_map": [{"key": "manager_type",
"values": ["aws-ec2"
]
}
],
"sort": "date_added"
}
}

Response samples

200
default

Content type

application/json

{"fields": ["string"
]
}

Search nodes

Searches the available nodes for a single node manager by id.

Authorization Action:

infra:nodeManagers:list

path Parameters

node_manager_id

required

string

Node manager ID.

Request Body schema: application/json
required

node_manager_id required	string Node manager ID.
	object (chef.automate.api.nodes.manager.v1.Query)

Responses

Request samples

Payload

Content type

application/json

{"node_manager_id": "string",
"query": {"filter_map": [{"key": "manager_type",
"values": ["aws-ec2"
]
}
],
"sort": "date_added"
}
}

Response samples

200
default

Content type

application/json

{"nodes": ["string"
],
"total": 0
}

Connect

Attempts to reach the API for the given nodemanager id to validate the credentials associated with the nodemanager.

Authorization Action:

infra:nodeManagers:rerun

path Parameters

id

required

string

UUID for the node manager.

Request Body schema: application/json
required

id

required

string

UUID for the node manager.

Responses

Request samples

Payload

Content type

application/json

{"uuid": "cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
}

Response samples

200
default

Content type

application/json

{ }

List all Node Managers

Returns a list of node managers. Supports filtering, sorting, and pagination.

Valid filtering fields: manager_type

Authorization Action:

infra:nodeManagers:list

Request Body schema: application/json
required

required	Array of objects (chef.automate.api.common.query.Filter) Filters for the query: "manager_type".
order	string (chef.automate.api.nodes.manager.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Sort the results in ascending or descending order.
page	integer <int32> Starting page for the list. For example, if your query returns 100 pages, and you know you're looking for a node manager somewhere in the middle, you might want to start on page 50.
per_page	integer <int32> Number of results on each page.
sort	string Field to use for sorting. Valid fields are: name, type, status, status_message, date_added.

Responses

Request samples

Payload

Content type

application/json

{"filter_map": [{"key": "manager_type",
"values": ["aws-ec2"
]
}
],
"sort": "date_added"
}

Response samples

200
default

Content type

application/json

{"total": "1"
}

Managed Nodes

Create a Node

Creates a node and adds it to the Chef Automate node manager. Requires a FQDN or IP address, a user-specified name, and a ssh or winrm credential reference. Useful for creating nodes for the purpose of running compliance scan jobs.

Example:

{
"name": "my-vagrant-node",
"manager":"automate",
"target_config": {
"backend":"ssh",
"host":"localhost",
"secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"],
"port": 22
},
"tags": [
{ "key":"test-node", "value":"is amazing" }
]
}

Authorization Action:

infra:nodes:create

Request Body schema: application/json
required

connection_error	string Last connection error received when trying to contact the node.
id	string Unique node ID (UUID).
last_contact	string <date-time> Timestamp of the last `detect` or `exec` job.
	object (chef.automate.api.nodes.v1.ResultsRow) Summary of the last Chef InSpec scan job run on the node.
manager	string Node manager (automate, aws-ec2, aws-api, azure-vm, azure-api, gcp).
manager_ids	Array of strings List of manager IDs for the node.
name	string User-specified node name.
name_prefix	string Prefix for node name. The full node name is the prefix + the host.
platform	string Node platform.
platform_version	string Node platform version.
projects	Array of strings List of projects associated with the node.
	object (chef.automate.api.nodes.v1.LastContactData) Most recent node data from the latest Chef Infra run and InSpec scan.
	object (chef.automate.api.nodes.v1.LastContactData) Most recent node data from the latest Chef Infra run and InSpec scan.
state	string Last known node state (running, stopped, terminated).
status	string Node status (unreachable, reachable, unknown).
	Array of objects (chef.automate.api.common.query.Kv) Node tags.
	object (chef.automate.api.nodes.v1.TargetConfig) Details for ssh/winrm access of the node.

Responses

Request samples

Payload

Content type

application/json

{"connection_error": "string",
"id": "string",
"last_contact": "2019-08-24T14:15:22Z",
"last_job": {"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
},
"manager": "string",
"manager_ids": ["string"
],
"name": "string",
"name_prefix": "string",
"platform": "string",
"platform_version": "string",
"projects": ["string"
],
"run_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"scan_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"state": "string",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"target_config": {"backend": "string",
"host": "string",
"hosts": ["string"
],
"port": 0,
"secrets": ["string"
],
"self_signed": true,
"ssl": true,
"sudo": true,
"sudo_options": "string",
"user": "string"
}
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

Bulk Create Nodes

Creates multiple nodes from a list of node data. hosts field is required. Multiple hosts may be defined in this field.

Example:

{
"name_prefix": "000-my-ssh-node",
"manager":"automate",
"target_config": {
"backend":"ssh",
"hosts":["localhost","127.0.0.1"],
"secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"],
"port": 22
},
"tags": [
{ "key":"test-node", "value":"is-amazing" },
]
}

Authorization Action:

infra:nodes:create

Request Body schema: application/json
required

	Array of objects (chef.automate.api.nodes.v1.Node) List of nodes.
total	integer <int32> Total number of nodes in the system.
total_reachable	integer <int32> Total number of reachable nodes in the system.
total_unknown	integer <int32> Total number of unknown nodes in the system.
total_unreachable	integer <int32> Total number of unreachable nodes in the system.

Responses

Request samples

Payload

Content type

application/json

{"nodes": [{"connection_error": "string",
"id": "string",
"last_contact": "2019-08-24T14:15:22Z",
"last_job": {"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
},
"manager": "string",
"manager_ids": ["string"
],
"name": "string",
"name_prefix": "string",
"platform": "string",
"platform_version": "string",
"projects": ["string"
],
"run_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"scan_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"state": "string",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"target_config": {"backend": "string",
"host": "string",
"hosts": ["string"
],
"port": 0,
"secrets": ["string"
],
"self_signed": true,
"ssl": true,
"sudo": true,
"sudo_options": "string",
"user": "string"
}
}
],
"total": 0,
"total_reachable": 0,
"total_unknown": 0,
"total_unreachable": 0
}

Response samples

200
default

Content type

application/json

{"ids": ["string"
]
}

Bulk Delete Nodes by Filter

Deletes a set of nodes that match a filter. Available filters: account_id, last_contact, manager_id, manager_type, name, platform_name, platform_release, region, source_id, state, statechange_timerange, status, last_run_timerange, last_scan_timerange, last_run_status, last_scan_status, last_run_penultimate_status, last_scan_penultimate_status

Example:

{"filters": [{"key": "name", "values": ["vj*"]}]}'

Authorization Action:

infra:nodes:delete

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Filter) Use filters to limit the set of nodes to delete.
order	string (chef.automate.api.nodes.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Return the results in ascending or descending order.
page	integer <int32> Starting page for the results.
per_page	integer <int32> The number of results on each page.
sort	string Sort the results on a specific field.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string"
}

Response samples

200
default

Content type

application/json

{"names": ["string"
]
}

Bulk Delete Nodes by ID

Deletes a set of nodes given a list of IDs. Invalid IDs will be ignored.

Authorization Action:

infra:nodes:delete

Request Body schema: application/json
required

ids	Array of strings List of node UUIDs.

Responses

Request samples

Payload

Content type

application/json

{"ids": ["string"
]
}

Response samples

200
default

Content type

application/json

{"names": ["string"
]
}

Show Node Details

Returns the details for a node given the node ID.

Authorization Action:

infra:nodes:get

path Parameters

id

required

string

Unique node ID (UUID)

Responses

Response samples

200
default

Content type

application/json

{"connection_error": "string",
"id": "string",
"last_contact": "2019-08-24T14:15:22Z",
"last_job": {"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
},
"manager": "string",
"manager_ids": ["string"
],
"name": "string",
"name_prefix": "string",
"platform": "string",
"platform_version": "string",
"projects": ["string"
],
"run_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"scan_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"state": "string",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"target_config": {"backend": "string",
"host": "string",
"hosts": ["string"
],
"port": 0,
"secrets": ["string"
],
"self_signed": true,
"ssl": true,
"sudo": true,
"sudo_options": "string",
"user": "string"
}
}

Update Node

This PUT operation overwrites ALL node details and requires the complete set of node details, consisting of a FQDN or IP address, a user-specified name, and the ID for an ssh or winrm credential. Substitute the desired values for the existing node details in the PUT message.

Authorization Action:

infra:nodes:update

path Parameters

id

required

string

Unique node ID (UUID).

Request Body schema: application/json
required

connection_error	string Last connection error received when trying to contact the node.
id	string Unique node ID (UUID).
last_contact	string <date-time> Timestamp of the last `detect` or `exec` job.
	object (chef.automate.api.nodes.v1.ResultsRow) Summary of the last Chef InSpec scan job run on the node.
manager	string Node manager (automate, aws-ec2, aws-api, azure-vm, azure-api, gcp).
manager_ids	Array of strings List of manager IDs for the node.
name	string User-specified node name.
name_prefix	string Prefix for node name. The full node name is the prefix + the host.
platform	string Node platform.
platform_version	string Node platform version.
projects	Array of strings List of projects associated with the node.
	object (chef.automate.api.nodes.v1.LastContactData) Most recent node data from the latest Chef Infra run and InSpec scan.
	object (chef.automate.api.nodes.v1.LastContactData) Most recent node data from the latest Chef Infra run and InSpec scan.
state	string Last known node state (running, stopped, terminated).
status	string Node status (unreachable, reachable, unknown).
	Array of objects (chef.automate.api.common.query.Kv) Node tags.
	object (chef.automate.api.nodes.v1.TargetConfig) Details for ssh/winrm access of the node.

Responses

Request samples

Payload

Content type

application/json

{"connection_error": "string",
"id": "string",
"last_contact": "2019-08-24T14:15:22Z",
"last_job": {"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
},
"manager": "string",
"manager_ids": ["string"
],
"name": "string",
"name_prefix": "string",
"platform": "string",
"platform_version": "string",
"projects": ["string"
],
"run_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"scan_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"state": "string",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"target_config": {"backend": "string",
"host": "string",
"hosts": ["string"
],
"port": 0,
"secrets": ["string"
],
"self_signed": true,
"ssl": true,
"sudo": true,
"sudo_options": "string",
"user": "string"
}
}

Response samples

200
default

Content type

application/json

null

Delete a Node

Deletes the node with the node ID.

Authorization Action:

infra:nodes:delete

path Parameters

id

required

string

Unique node ID (UUID)

Responses

Response samples

200
default

Content type

application/json

null

List Node Status

Use this to run an inspec detect job on the node, which updates the status to reflect that the node is reachable or unreachable.

Authorization Action:

infra:nodes:rerun

path Parameters

id

required

string

Unique node ID (UUID)

Responses

Response samples

200
default

Content type

application/json

{ }

List and Filter Nodes

Makes a list of nodes. Supports filtering, pagination, and sorting. Adding a filter narrows the list of nodes to only those that match the filter or filters. Supported filters: account_id, last_contact, manager_id, manager_type, name, platform_name, platform_release, region, source_id, state, statechange_timerange, status, last_run_timerange, last_scan_timerange, last_run_status, last_scan_status, last_run_penultimate_status, last_scan_penultimate_status

Example:

{
"filters":[
{"key": "last_scan_status", "values": ["FAILED"]},
{"key": "last_scan_penultimate_status", "values": ["PASSED"]},
{"key": "name", "values": ["MyNode*"]}
],
"page":1, "per_page":100,
"sort":"status", "order":"ASC"
}

Authorization Action:

infra:nodes:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Filter) Use filters to limit the set of nodes to delete.
order	string (chef.automate.api.nodes.v1.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Return the results in ascending or descending order.
page	integer <int32> Starting page for the results.
per_page	integer <int32> The number of results on each page.
sort	string Sort the results on a specific field.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string"
}

Response samples

200
default

Content type

application/json

{"nodes": [{"connection_error": "string",
"id": "string",
"last_contact": "2019-08-24T14:15:22Z",
"last_job": {"end_time": "2019-08-24T14:15:22Z",
"job_id": "string",
"node_id": "string",
"report_id": "string",
"result": "string",
"start_time": "2019-08-24T14:15:22Z",
"status": "string"
},
"manager": "string",
"manager_ids": ["string"
],
"name": "string",
"name_prefix": "string",
"platform": "string",
"platform_version": "string",
"projects": ["string"
],
"run_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"scan_data": {"end_time": "2019-08-24T14:15:22Z",
"id": "string",
"penultimate_status": "UNKNOWN",
"status": "UNKNOWN"
},
"state": "string",
"status": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"target_config": {"backend": "string",
"host": "string",
"hosts": ["string"
],
"port": 0,
"secrets": ["string"
],
"self_signed": true,
"ssl": true,
"sudo": true,
"sudo_options": "string",
"user": "string"
}
}
],
"total": 0,
"total_reachable": 0,
"total_unknown": 0,
"total_unreachable": 0
}

Event Feed

List Counts of Individual Event Tasks

Returns the total counts of actions taken in an event. The counted actions are: update, create, and delete.

Example:

event_task_counts?start=1592546400000&end=1593151199999

Authorization Action:

event:events:list

query Parameters

filter	Array of strings Filters to be applied to the request.
start	string <int64> Earliest events to return.
end	string <int64> Latest events to return.

Responses

Response samples

200
default

Content type

application/json

{"counts": [{"count": "string",
"name": "string"
}
],
"total": "string"
}

List Counts of Event Types

Returns totals for role, cookbook, and organization events.

Example:

event_type_counts?start=1592546400000&end=1593151199999

Authorization Action:

event:events:list

query Parameters

filter	Array of strings Filters to be applied to the request.
start	string <int64> Earliest events to return.
end	string <int64> Latest events to return.

Responses

Response samples

200
default

Content type

application/json

{"counts": [{"count": "string",
"name": "string"
}
],
"total": "string"
}

List Events

Returns a list of recorded events in Chef Automate, such as Infra Server events (cookbook creation, policyfile updates, and node creation) and Chef Automate internal events (profile installs and scan job creation). Adding a filter makes a list of all events that meet the filter criteria.

Example:

eventfeed?collapse=true&filter=organization:4thcafe&page_size=100&start=1592546400000&end=1593151199999

Authorization Action:

event:events:list

query Parameters

filter	Array of strings Filters to be applied to the request.
start	string <int64> Earliest events to return.
end	string <int64> Latest events to return.
page_size	integer <int32> Count of events to return per page.
after	string <int64> Used for pagination, to request results in ascending order.
before	string <int64> Used for pagination, to request results in descending order.
cursor	string Used for pagination, to bookmark next set of results.
collapse	boolean <boolean> Used to group similar events together.

Responses

Response samples

200
default

Content type

application/json

{"events": [{"chef_infra_server": "string",
"chef_organization": "string",
"end_id": "string",
"end_time": "2019-08-24T14:15:22Z",
"entity_name": "string",
"event_count": 0,
"event_type": "string",
"parent_name": "string",
"parent_type": "string",
"requestor_name": "string",
"requestor_type": "string",
"service_hostname": "string",
"start_id": "string",
"start_time": "2019-08-24T14:15:22Z",
"task": "string"
}
],
"total_events": "string"
}

List Summary Data of Events

Returns data that populates the guitar strings visual on the top of the event feed.

Example:

eventstrings?timezone=America/Denver&hours_between=1&start=2020-06-19&end=2020-06-25

Authorization Action:

event:events:list

query Parameters

start	string Earliest events to return.
end	string Latest events to return.
timezone	string User timezone to apply to request.
hours_between	integer <int32> Interval for returned results, for example: 1 hour buckets.
filter	Array of strings Filters to be applied to the request.

Responses

Response samples

200
default

Content type

application/json

{"end": "string",
"hours_between": 0,
"start": "string",
"strings": [{"collection": [{"events_count": [{"count": "string",
"name": "string"
}
]
}
],
"event_action": "string"
}
]
}

Secrets

Create a secret

Creates a secret. Requires values for name, type, and data.

Supported types: ssh, winrm, sudo, aws, azure, gcp, service_now Supported keys by type: ssh: username, password, key winrm: username, password sudo: username, password service_now: username, password aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN azure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID azure: AZURE_SUBSCRIPTION_ID is optional gcp: GOOGLE_CREDENTIALS_JSON

Example:

{
"name": "my ssh secret",
"type": "ssh",
"data": [
{ "key": "username", "value": "vagrant" },
{ "key": "password", "value": "vagrant"} 
]
}

Authorization Action:

secrets:secrets:create

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Kv) Secret data, where the kv structs for the credential data live.
id	string Unique node ID (UUID).
last_modified	string <date-time> Timestamp denoting when the secret was last modified.
name	string User-specified name for the secret.
	Array of objects (chef.automate.api.common.query.Kv) Tags to associate with the secret.
type	string (Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now)

Responses

Request samples

Payload

Content type

application/json

{"data": [{"key": "string",
"value": "string"
}
],
"id": "string",
"last_modified": "2019-08-24T14:15:22Z",
"name": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"type": "string"
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

Read a secret

Reads a secret given the ID of the secret. Note that the secret information (password and key values) will not be returned by the API, as a safety measure.

Authorization Action:

secrets:secrets:get

path Parameters

id

required

string

Unique node ID (UUID).

Responses

Response samples

200
default

Content type

application/json

{"data": [{"key": "string",
"value": "string"
}
],
"id": "string",
"last_modified": "2019-08-24T14:15:22Z",
"name": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"type": "string"
}

Delete a secret

Deletes a secret given the ID of the secret. Note that any nodes that were using the secret will no longer be associated with the deleted secret.

Authorization Action:

secrets:secrets:delete

path Parameters

id

required

string

Unique node ID (UUID).

Responses

Response samples

200
default

Content type

application/json

{ }

Update a secret

Updates a secret. This is a PATCH operation, meaning the details sent in will override/replace those stored in the DB. Secret information that is not in the body of the request will persist.

Example:

given a credential with a username and password, a user could update the password by passing in the following body, 
and the name of the secret as well as the username for the secret be unchanged:

{
"id": "525c013a-2ab3-4e6f-9005-51bc620e9157",
"data": [
{ "key": "password", "value": "new-value"} 
]
}

Authorization Action:

secrets:secrets:update

path Parameters

id

required

string

Unique node ID (UUID).

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Kv) Secret data, where the kv structs for the credential data live.
id	string Unique node ID (UUID).
last_modified	string <date-time> Timestamp denoting when the secret was last modified.
name	string User-specified name for the secret.
	Array of objects (chef.automate.api.common.query.Kv) Tags to associate with the secret.
type	string (Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now)

Responses

Request samples

Payload

Content type

application/json

{"data": [{"key": "string",
"value": "string"
}
],
"id": "string",
"last_modified": "2019-08-24T14:15:22Z",
"name": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"type": "string"
}

Response samples

200
default

Content type

application/json

{ }

List and filter secrets

Makes a list of secrets. Supports filtering, pagination, and sorting. Adding a filter narrows the list of secrets to only those that match the filter or filters. Supported filters: type, name Supported sort types: name, type, last modified

Example:

{
"sort": "type",
"order": "ASC",
"filters": [
{ "key": "type", "values": ["ssh","winrm","sudo"] }
],
"page":1,
"per_page":100
}

Authorization Action:

secrets:secrets:list

Request Body schema: application/json
required

	Array of objects (chef.automate.api.common.query.Filter) Use filters to limit the set of secrets.
order	string (chef.automate.api.secrets.Query.OrderType) Default: "ASC" Enum: "ASC" "DESC" Return the results in ascending or descending order.
page	integer <int32> Starting page for the results.
per_page	integer <int32> The number of results on each page.
sort	string Sort the results on a specific field.

Responses

Request samples

Payload

Content type

application/json

{"filters": [{"exclude": true,
"key": "string",
"values": ["string"
]
}
],
"order": "ASC",
"page": 0,
"per_page": 0,
"sort": "string"
}

Response samples

200
default

Content type

application/json

{"secrets": [{"data": [{"key": "string",
"value": "string"
}
],
"id": "string",
"last_modified": "2019-08-24T14:15:22Z",
"name": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"type": "string"
}
],
"total": 0
}

Service Groups and Services

Remove Disconnected Services

Removes services marked as disconnected based on the threshold_seconds setting. This function is not used by the API or CLI and is here for testing purposes. The functionality is currently covered by a periodically running job that can be configured using UpdateDeleteDisconnectedServicesConfig.

Authorization Action:

applications:serviceGroups:delete

Request Body schema: application/json
required

threshold_seconds

integer <int32>

Threshold for marking services disconnected in seconds.

Responses

Request samples

Payload

Content type

application/json

{"threshold_seconds": 0
}

Response samples

200
default

Content type

application/json

{"services": [{"application": "string",
"channel": "string",
"current_health_since": "string",
"disconnected": true,
"environment": "string",
"fqdn": "string",
"group": "string",
"health_check": "OK",
"health_check_result": {"exit_status": 0,
"stderr": "string",
"stdout": "string"
},
"health_updated_at": "2019-08-24T14:15:22Z",
"id": "string",
"last_event_occurred_at": "2019-08-24T14:15:22Z",
"last_event_since": "string",
"previous_health_check": "OK",
"release": "string",
"site": "string",
"supervisor_id": "string",
"update_strategy": "string"
}
]
}

Delete the services with the given IDs

Authorization Action:

applications:serviceGroups:delete

Request Body schema: application/json
required

ids	Array of strings List of the database IDs of the services to be deleted.

Responses

Request samples

Payload

Content type

application/json

{"ids": ["string"
]
}

Response samples

200
default

Content type

application/json

{"services": [{"application": "string",
"channel": "string",
"current_health_since": "string",
"disconnected": true,
"environment": "string",
"fqdn": "string",
"group": "string",
"health_check": "OK",
"health_check_result": {"exit_status": 0,
"stderr": "string",
"stdout": "string"
},
"health_updated_at": "2019-08-24T14:15:22Z",
"id": "string",
"last_event_occurred_at": "2019-08-24T14:15:22Z",
"last_event_since": "string",
"previous_health_check": "OK",
"release": "string",
"site": "string",
"supervisor_id": "string",
"update_strategy": "string"
}
]
}

Mark Services as Disconnected

Marks services as disconnected based on the threshold_seconds setting. This function is not used by the API or CLI and is here for testing purposes. The functionality is currently covered by a periodically running job that can be configured by utilizing the UpdateDisconnectedServicesConfig endpoint.

Authorization Action:

applications:serviceGroups:list

query Parameters

threshold_seconds

integer <int32>

Threshold for marking services disconnected in seconds.

Responses

Response samples

200
default

Content type

application/json

{"services": [{"application": "string",
"channel": "string",
"current_health_since": "string",
"disconnected": true,
"environment": "string",
"fqdn": "string",
"group": "string",
"health_check": "OK",
"health_check_result": {"exit_status": 0,
"stderr": "string",
"stdout": "string"
},
"health_updated_at": "2019-08-24T14:15:22Z",
"id": "string",
"last_event_occurred_at": "2019-08-24T14:15:22Z",
"last_event_since": "string",
"previous_health_check": "OK",
"release": "string",
"site": "string",
"supervisor_id": "string",
"update_strategy": "string"
}
]
}

List Service Groups

Lists service groups with name, health information, and application, environment, package, release metadata. Accepts pagination, sorting, search, and status filters.

Example:

applications/service-groups?sorting.field=percent_ok&sorting.order=ASC&pagination.page=1&pagination.size=25

Authorization Action:

applications:serviceGroups:list

query Parameters

filter	Array of strings Applies search and status filters, in the format of `fieldname:value` or `status:value`. Valid filter fieldnames are: `origin`: origin component of the service's package identifier `service`: the name component of the service's package identifier `version`: the version number component of the service's package identifier `buildstamp`: the build timestamp (also called "release") of the service's package identifier `channel`: the package channel to which the service subscribes for updates `application`: the application field of the service's event-stream metadata `environment`: the environment field of the service's event-stream metadata `site`: the site field of the service's event-stream metadata `group`: the suffix of the service group name `status` filters refine the service group results by a service's most recent connected/disconnected state or healthcheck result. Valid status filter parameters are: `status:disconnected`: returns service groups with at least one service in a disconnected state `status:critical`: returns service groups with a with at least one service in a "critical" healthcheck result `status:unknown`: returns service groups with at least one service with an "unknown" healthcheck result `status:warning`: returns service groups with at least one service with a "warning" healthcheck result `status:ok`: returns service groups with at least one service with an "ok" health check result
pagination.page	integer <int32> Page number of the results to return.
pagination.size	integer <int32> Amount of results to include per page.
sorting.field	string Field to sort the list results on.
sorting.order	string Default: "ASC" Enum: "ASC" "DESC" Order the results should be returned in.

Responses

Response samples

200
default

Content type

application/json

{"service_groups": [{"application": "string",
"disconnected_count": 0,
"environment": "string",
"health_percentage": 0,
"id": "string",
"name": "string",
"package": "string",
"release": "string",
"services_health_counts": {"critical": 0,
"disconnected": 0,
"ok": 0,
"total": 0,
"unknown": 0,
"warning": 0
},
"status": "OK"
}
]
}

List Services for a Service Group

List the services for a service group with health status and service metadata. Uses the service group ID generated by Chef Automate instead of the Chef Habitat- provided ID. Supports pagination and filtering.

Example:

applications/service-groups/1dfff679054c60a10c51d059b6dbf81a765c46f8d3e8ce0752b22ffe8d4d9716?pagination.page=1&pagination.size=25

Authorization Action:

applications:serviceGroups:list

path Parameters

service_group_id

required

string

Service group ID.

query Parameters

pagination.page	integer <int32> Page number of the results to return.
pagination.size	integer <int32> Amount of results to include per page.
sorting.field	string Field to sort the list results on.
sorting.order	string Default: "ASC" Enum: "ASC" "DESC" Order the results should be returned in.
filter	Array of strings Applies filters, in the format of `fieldname:value`. See documentation for ServicesReq for valid filter parameters.

Responses

Response samples

200
default

Content type

application/json

{"group": "string",
"services": [{"application": "string",
"channel": "string",
"current_health_since": "string",
"disconnected": true,
"environment": "string",
"fqdn": "string",
"group": "string",
"health_check": "OK",
"health_check_result": {"exit_status": 0,
"stderr": "string",
"stdout": "string"
},
"health_updated_at": "2019-08-24T14:15:22Z",
"id": "string",
"last_event_occurred_at": "2019-08-24T14:15:22Z",
"last_event_since": "string",
"previous_health_check": "OK",
"release": "string",
"site": "string",
"supervisor_id": "string",
"update_strategy": "string"
}
],
"services_health_counts": {"critical": 0,
"disconnected": 0,
"ok": 0,
"total": 0,
"unknown": 0,
"warning": 0
}
}

List Service Groups Health Counts

Lists the total service group health reports by critical, warning, ok and unknown responses. Supports search and status filtering.

Authorization Action:

applications:serviceGroups:list

query Parameters

filter

Array of strings

Applies search filters, in the format of fieldname:value. See the documentation for ServiceGroupsReq for valid filter parameters.

Responses

Response samples

200
default

Content type

application/json

{"critical": 0,
"disconnected": 0,
"ok": 0,
"total": 0,
"unknown": 0,
"warning": 0
}

List Services

Lists service health status and service metadata for services. Supports pagination and search and status filtering. For a list of services for a specific service-group see "List Services for a Service Group" (GetServicesBySG endpoint).

Authorization Action:

applications:serviceGroups:list

query Parameters

filter	Array of strings Applies search filters, in the format of `fieldname:value`. Valid filter fieldnames are: `origin`: origin component of the service's package identifier `service`: the name component of the service's package identifier `version`: the version number component of the service's package identifier `buildstamp`: the build timestamp (also called "release") of the service's package identifier `channel`: the package channel to which the service subscribes for updates `application`: the application field of the service's event-stream metadata `environment`: the environment field of the service's event-stream metadata `site`: the site field of the service's event-stream metadata `group`: the suffix of the service group name `status` filters refine service results by a service's current state or most recent healthcheck result. Disconnected services keep their last healthcheck result until their reports are removed by Chef Automate. When you apply a healthcheck filter, the report includes all recently disconnected services. Valid status filter parameters are: `status:disconnected`: returns services in a disconnected state `status:critical`: returns services with a "critical" healthcheck result `status:unknown`: returns services with an "unknown" healthcheck result `status:warning`: returns services with a "warning" healthcheck result `status:ok`: returns services with an "ok" health check result
pagination.page	integer <int32> Page number of the results to return.
pagination.size	integer <int32> Amount of results to include per page.
sorting.field	string Field to sort the list results on.
sorting.order	string Default: "ASC" Enum: "ASC" "DESC" Order the results should be returned in.

Responses

Response samples

200
default

Content type

application/json

{"services": [{"application": "string",
"channel": "string",
"current_health_since": "string",
"disconnected": true,
"environment": "string",
"fqdn": "string",
"group": "string",
"health_check": "OK",
"health_check_result": {"exit_status": 0,
"stderr": "string",
"stdout": "string"
},
"health_updated_at": "2019-08-24T14:15:22Z",
"id": "string",
"last_event_occurred_at": "2019-08-24T14:15:22Z",
"last_event_since": "string",
"previous_health_check": "OK",
"release": "string",
"site": "string",
"supervisor_id": "string",
"update_strategy": "string"
}
]
}

List Filter Values

Lists all of the possible filter values for a given valid field. Limit the returned values by providing at one or more characters in the query_fragment parameter. Supports wildcard (* and ?)

Authorization Action:

applications:serviceGroups:list

query Parameters

field_name	string Field name of service values.
query_fragment	string Query value, supports wildcards (* and ?).
filter	Array of strings Applies filters, in the format of `fieldname:value`. See documentation for ServicesReq for valid filter parameters.

Responses

Response samples

200
default

Content type

application/json

{"values": ["string"
]
}

Show Summary

Shows a summary of service-groups, services, deployments, and supervisors. Used for telemetry. Does not support filtering.

Authorization Action:

applications:serviceGroups:list

Responses

Response samples

200
default

Content type

application/json

{"total_deployments": 0,
"total_service_groups": 0,
"total_services": 0,
"total_supervisors": 0
}

Service Management

Show 'Remove Disconnected Services' Configuration

Displays configuration for the task that deletes services marked as disconnected after 'threshold'. Threshold is a string that follows Elasticsearch's date math expressions. This job is disabled if running is set to false.

Authorization Action:

retention:serviceGroups:get

Responses

Response samples

200
default

Content type

application/json

{"job_info": {"last_elapsed": "string",
"last_ended_at": "2019-08-24T14:15:22Z",
"last_enqueued_at": "2019-08-24T14:15:22Z",
"last_started_at": "2019-08-24T14:15:22Z",
"next_due_at": "2019-08-24T14:15:22Z"
},
"recurrence": "string",
"running": true,
"threshold": "string"
}

Change 'Remove Disconnected Services' Configuration

Updates configuration information for the task that deletes services marked as disconnected after 'threshold'. Threshold is a string that follows Elasticsearch's date math expressions. This job can be disabled by setting "running": false.

The frequency of the job's execution can be modified by changing the 'recurrence'. This setting is a string as defined in section 4.3.10 of RFC 2445. By default, the task runs every 60 seconds. It is not recommended to change the recurrence.

Example:

service_groups/delete_disconnected_services/config" -d
'{
"threshold": "1d",
"running":true,
"recurrence": "FREQ=SECONDLY;DTSTART=20200612T182166Z;INTERVAL=60"
}'

Authorization Action:

retention:serviceGroups:update

Request Body schema: application/json
required

	object (chef.automate.api.applications.PeriodicJobInfo) PeriodicJobInfo gives information about the last and next scheduled executions of a periodic job.
recurrence	string A recurrence rule that determines how often, at what interval, and when to initially start a scheduled job. If the field is omitted from the request or is set to an emtpy string, no change will be made to the current value. Otherwise, the value should match the recurrence rule format defined in section 4.3.10 of RFC 2445. It is not recommended to change this value from the default setting of a 60 second interval. This configuration option is provided only for consistency with other data lifecyle APIs.
running	boolean <boolean> Enable/disable the job. `false` is disabled, `true` is enabled.
threshold	string The `threshold` setting used by periodic jobs for evaluating services. Threshold is a string that follows Elasticsearch's date math expressions. For more information, see the simpledatemath package under `lib/`.

Responses

Request samples

Payload

Content type

application/json

{"job_info": {"last_elapsed": "string",
"last_ended_at": "2019-08-24T14:15:22Z",
"last_enqueued_at": "2019-08-24T14:15:22Z",
"last_started_at": "2019-08-24T14:15:22Z",
"next_due_at": "2019-08-24T14:15:22Z"
},
"recurrence": "string",
"running": true,
"threshold": "string"
}

Response samples

200
default

Content type

application/json

{ }

ApplicationsService_RunDeleteDisconnectedServicesJob

Request Body schema: application/json
required

object (chef.automate.api.applications.RunDeleteDisconnectedServicesJobReq)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{ }

Show 'Disconnected Services' configuration

Returns the configuration for the task that marks services as disconnected. The threshold setting defines the period of time between the last report from a node and the moment when Chef Automate marks it as disconnected. Threshold is a string that follows Elasticsearch's date math expressions. This task is always enabled, cannot be disabled. Because this task runs continuously, the response does not return information about its status.

Authorization Action:

retention:serviceGroups:get

Responses

Response samples

200
default

Content type

application/json

{"job_info": {"last_elapsed": "string",
"last_ended_at": "2019-08-24T14:15:22Z",
"last_enqueued_at": "2019-08-24T14:15:22Z",
"last_started_at": "2019-08-24T14:15:22Z",
"next_due_at": "2019-08-24T14:15:22Z"
},
"recurrence": "string",
"running": true,
"threshold": "string"
}

Change 'Disconnected Services' Configuration

Changes the configuration for the task that marks services as disconnected.

The periodic task to check for disconnected services can be enabled or disabled by setting the 'running' setting to true or false, respectively. When disabled, no services will be marked disconnected, regardless of the time that has elapsed since the last health check. It is not recommened to disable the job.

The frequency of the job's execution can be modified by changing the 'recurrence'. This setting is a string as defined in section 4.3.10 of RFC 2445. By default, the task runs every 60 seconds. It is not recommended to change the recurrence.

When enabled, services are marked disconnected when the time elapsed since Automate last received a health check exceeds 'threshold'. Threshold is a string that follows Elasticsearch's date math expressions.

Example:

/retention/service_groups/disconnected_services/config
'{
"threshold": "15m",
"running": true,
"recurrence": "FREQ=SECONDLY;DTSTART=20200612T182166Z;INTERVAL=60"
}'

Authorization Action:

retention:serviceGroups:update

Request Body schema: application/json
required

	object (chef.automate.api.applications.PeriodicJobInfo) PeriodicJobInfo gives information about the last and next scheduled executions of a periodic job.
recurrence	string A recurrence rule that determines how often, at what interval, and when to initially start a scheduled job. If the field is omitted from the request or is set to an emtpy string, no change will be made to the current value. Otherwise, the value should match the recurrence rule format defined in section 4.3.10 of RFC 2445. It is not recommended to change this value from the default setting of a 60 second interval. This configuration option is provided only for consistency with other data lifecyle APIs.
running	boolean <boolean> Enable/disable the job. `false` is disabled, `true` is enabled. It is not recommended to disable this job.
threshold	string The `threshold` setting used by periodic jobs for evaluating services. Threshold is a string that follows Elasticsearch's date math expressions. For more information, see the simpledatemath package under `lib/`.

Responses

Request samples

Payload

Content type

application/json

{"job_info": {"last_elapsed": "string",
"last_ended_at": "2019-08-24T14:15:22Z",
"last_enqueued_at": "2019-08-24T14:15:22Z",
"last_started_at": "2019-08-24T14:15:22Z",
"next_due_at": "2019-08-24T14:15:22Z"
},
"recurrence": "string",
"running": true,
"threshold": "string"
}

Response samples

200
default

Content type

application/json

{ }

Runs the job to mark services as disconnected immediately.

Authorization Action:

retention:serviceGroups:update

Request Body schema: application/json
required

object (chef.automate.api.applications.RunDisconnectedServicesJobReq)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{ }

IAM Users

IAM local users are not attached to external identity providers. They can be members of IAM teams and IAM policies.

Update self (as user)

Updates a local user's own name or password. If changing the password, both "password" and "previous_password" are required.

Authorization Action:

iam:usersSelf:update

path Parameters

id

required

string

ID of the user. Cannot be changed. Used to sign in.

Request Body schema: application/json
required

id	string ID of the user. Cannot be changed. Used to sign in.
name required	string Display name for local user.
password	string New password for user. Used to sign in. Optional, but if included, previous_password is also required.
previous_password	string Previous password for user. Optional, but if included, password is also required.

Responses

Request samples

Payload
JSON

Content type

application/json

{"name": "My New Name",
"password": "aNewSafePassword",
"previous_password": "aPreviousSafePassword"
}

Response samples

200
default

Content type

application/json

{"user": {"id": "string",
"membership_id": "string",
"name": "string"
}
}

List all users

Lists all local users.

Authorization Action:

iam:users:list

Responses

Response samples

200
default

Content type

application/json

{"users": [{"id": "string",
"membership_id": "string",
"name": "string"
}
]
}

Create a user

Creates a local user that can sign in to Automate and be a member of IAM teams and IAM policies.

Authorization Action:

iam:users:create

Request Body schema: application/json
required

id required	string Unique ID. Cannot be changed. Used to sign in.
name required	string Display name for local user.
password required	string Password for user. Used to sign in.

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "username001rulez",
"name": "Display Name",
"password": "aSafePassword"
}

Response samples

200
default

Content type

application/json

{"user": {"id": "string",
"membership_id": "string",
"name": "string"
}
}

Get a user

Returns the details for a local user.

Authorization Action:

iam:users:get

path Parameters

id

required

string

ID of the user.

Responses

Response samples

200
default

Content type

application/json

{"user": {"id": "string",
"membership_id": "string",
"name": "string"
}
}

Update a user

Updates a local user's name or password.

Authorization Action:

iam:users:update

path Parameters

id

required

string

ID of the user. Cannot be changed. Used to sign in.

Request Body schema: application/json
required

id	string ID of the user. Cannot be changed. Used to sign in.
name required	string Display name for local user.
password	string Password used to log in. Will overwrite preexisting password.

Responses

Request samples

Payload
JSON

Content type

application/json

{"name": "New Name",
"password": "aSafePassword"
}

Response samples

200
default

Content type

application/json

{"user": {"id": "string",
"membership_id": "string",
"name": "string"
}
}

Delete a user

Deletes a local user.

Authorization Action:

iam:users:delete

path Parameters

id

required

string

ID of the user.

Responses

Response samples

200
default

Content type

application/json

{ }

IAM Teams

Teams are used to group local users for policy membership.

Lists all local teams

Lists all local teams.

Authorization Action:

iam:teams:list

Responses

Response samples

200
default

Content type

application/json

{"teams": [{"id": "test-1",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
},
{"id": "test-2",
"name": "My Test Team 2",
"projects": ["project1"
]
}
]
}

Creates a local team

Creates a local team that is used to group local users as members of IAM policies.

Authorization Action:

iam:teams:create

Request Body schema: application/json
required

id required	string
name required	string
projects	Array of strings

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "my-team-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}

Response samples

200
default

Content type

application/json

{"team": {"id": "test-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}
}

Get a team

Returns the details for a team.

Authorization Action:

iam:teams:get

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"team": {"id": "test-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}
}

Updates a local team

Updates a local team.

Authorization Action:

iam:teams:update

path Parameters

id

required

string

Request Body schema: application/json
required

id required	string
name required	string
projects	Array of strings

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "my-team-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}

Response samples

200
default

Content type

application/json

{"team": {"id": "test-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}
}

Deletes a local team

Deletes a local team and removes it from any policies.

Authorization Action:

iam:teams:delete

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"team": {"id": "test-id",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
}
}

Gets local team membership

Lists all users of a local team. Users are listed by their membership_id.

Authorization Action:

iam:teamUsers:list

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"membership_ids": ["527ed96f-2ecb-4f8f-abd7-0bf6511459ac",
"353a62d4-85fa-4423-b12a-f6608a562ae9"
]
}

Adds local team membership

Adds a list of users to a local team. Users are added by their membership_id. The request currently does not validate that membership_id maps to a real user.

The membership_id for users can be found via GET /apis/apis/iam/v2/users/.

Authorization Action:

iam:teamUsers:create

path Parameters

id

required

string

Request Body schema: application/json
required

id required	string
membership_ids required	Array of strings

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "admins",
"membership_ids": ["527ed96f-2ecb-4f8f-abd7-0bf6511459ac",
"353a62d4-85fa-4423-b12a-f6608a562ae9"
]
}

Response samples

200
default

Content type

application/json

{"membership_ids": ["527ed96f-2ecb-4f8f-abd7-0bf6511459ac",
"353a62d4-85fa-4423-b12a-f6608a562ae9"
]
}

Removes local team membership

Removes a list of users from a local team. Users are removed by their membership_id. The request currently does not validate that membership_id maps to a real user.

The membership_id for users can be found via GET /apis/apis/iam/v2/users/.

Authorization Action:

iam:teamUsers:delete

path Parameters

id

required

string

Request Body schema: application/json
required

id required	string
membership_ids required	Array of strings

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "admins",
"membership_ids": ["527ed96f-2ecb-4f8f-abd7-0bf6511459ac",
"353a62d4-85fa-4423-b12a-f6608a562ae9"
]
}

Response samples

200
default

Content type

application/json

{"membership_ids": ["527ed96f-2ecb-4f8f-abd7-0bf6511459ac",
"353a62d4-85fa-4423-b12a-f6608a562ae9"
]
}

Gets team membership for a user

Lists all local teams for a specific user. You must use their membership_id in the request URL.

Authorization Action:

iam:userTeams:get

path Parameters

membership_id

required

string

Responses

Response samples

200
default

Content type

application/json

{"teams": [{"id": "test-1",
"name": "My Test Team",
"projects": ["project1",
"project2"
]
},
{"id": "test-2",
"name": "My Test Team 2",
"projects": ["project1"
]
}
]
}

IAM API Tokens

Tokens are used for API access to Automate endpoints as well as by systems (e.g. Chef Infra Servers) to communicate with Automate.

Lists all tokens

Lists all tokens, both admin and non-admin.

Authorization Action:

iam:tokens:list

Responses

Response samples

200
default

Content type

application/json

{"tokens": [{"active": true,
"id": "token-1",
"name": "token 1",
"projects": ["east-region",
"west-region"
]
},
{"active": false,
"id": "token-2",
"name": "token 2",
"projects": ["north-region",
"south-region"
]
}
]
}

Creates a token

Creates a token. Active defaults to true when not specified. Value is auto-generated when not specified.

Note that this creates non-admin tokens that may then be assigned permissions via policies just like users or teams (unless you have already created policies that encompass all tokens using `tokens:*``).

You cannot create admin tokens via the REST API. Admin tokens can only be created by specifying the --admin flag to this chef-automate sub-command:

chef-automate iam token create <your-token-name> --admin`

Authorization Action:

iam:tokens:create

Request Body schema: application/json
required

active	boolean <boolean> Active state. Defaults to true. If set to false, token will not be authenticated or authorized.
id required	string Unique ID. Cannot be changed.
name required	string Name for the token.
projects	Array of strings List of projects this token belongs to.
value	string Unique value for the token; if omitted the system will generate this.

Responses

Request samples

Payload
JSON

Content type

application/json

{"active": true,
"id": "token-1",
"name": "token 1",
"projects": ["east-region",
"west-region"
]
}

Response samples

200
default

Content type

application/json

{"active": true,
"id": "token-1",
"name": "token 1",
"projects": ["east-region",
"west-region"
]
}

Gets a token

Returns the details for a token.

Authorization Action:

iam:tokens:get

path Parameters

id

required

string

ID of the token.

Responses

Response samples

200
default

Content type

application/json

{"active": true,
"id": "token-1",
"name": "token 1",
"projects": ["east-region",
"west-region"
]
}

Updates a token

This operation overwrites all fields excepting ID, timestamps, and value, including those omitted from the request, so be sure to specify all properties. Properties that you do not include are reset to empty values.

Authorization Action:

iam:tokens:update

path Parameters

id

required

string

Unique ID. Cannot be changed.

Request Body schema: application/json
required

active	boolean <boolean> Active state. Defaults to true. If set to false, token will not be authenticated or authorized.
id	string Unique ID. Cannot be changed.
name required	string Name for the token.
projects	Array of strings List of projects this token belongs to.

Responses

Request samples

Payload
JSON

Content type

application/json

{"active": true,
"name": "updated token name",
"projects": ["east-region",
"south-region"
]
}

Response samples

200
default

Content type

application/json

{"active": true,
"id": "token-1",
"name": "token 1",
"projects": ["east-region",
"west-region"
]
}

Deletes a token

Deletes a token and remove it from any policies.

Authorization Action:

iam:tokens:delete

path Parameters

id

required

string

ID of the token.

Responses

Response samples

200
default

Content type

application/json

{ }

IAM Policies

A policy defines permissions for who may perform what action on which resources, based on the project. The ‘who’ is a user, a team, or a system. A policy has three components, the agent, the action, and the project. The agent is a user, team, or system. Users and teams are designated by name while systems communicate with Chef Automate using pre-authorized API tokens. Actions are activities that agents can take in relation to Chef Automate’s content and operation. Projects are collections of resources, such as API tokens or ingested compliance nodes.

Lists all policies

Lists all policies.

Authorization Action:

iam:policies:list

Responses

Response samples

200
default

Content type

application/json

{"policies": [{"id": "custom-viewer-policy-1",
"members": ["team:ldap:*"
],
"name": "My Viewer Policy 1",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
},
{"id": "custom-policy-2",
"members": ["team:local:test"
],
"name": "My Custom Policy 2",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1"
],
"role": "auditor"
}
]
}
]
}

Creates a custom policy

Creates a custom IAM policy used to control permissions in Automate. A policy is composed of one or more statements that grant permissions to a set of members. Each statement contains a role as well as a list of projects.

The role defines a set of actions that the statement is scoped to. The project list defines the set of resources that the statement is scoped to. Pass "projects": ["*"] to scope a statement to every project.

A policy's top-level projects list defines which projects the policy belongs to (for filtering policies by their projects), whereas the statement-level projects list defines which projects the statement applies to.

The example creates a new policy not associated with any project (because the top-level projects property is empty) that grants the viewer role on a few projects for all LDAP teams and a custom role qa on a specific project.

Authorization Action:

iam:policies:create

Request Body schema: application/json
required

id required	string Unique ID. Cannot be changed.
members	Array of strings Members affected by this policy.
name required	string Name for the policy.
projects	Array of strings List of projects this policy belongs to.
required	Array of objects (chef.automate.api.iam.v2.Statement) Statements for the policy.

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "custom-viewer-policy",
"members": ["team:ldap:*"
],
"name": "My Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Response samples

200
default

Content type

application/json

{"id": "custom-viewer-policy",
"members": ["team:ldap:*"
],
"name": "My Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Gets a policy

Returns the details for a policy.

Authorization Action:

iam:policies:get

path Parameters

id

required

string

ID of the policy.

Responses

Response samples

200
default

Content type

application/json

{"id": "custom-viewer-policy",
"members": ["team:ldap:*"
],
"name": "My Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Updates a custom policy

This operation overwrites all fields excepting ID, including those omitted from the request, so be sure to specify all properties. Properties that you do not include are reset to empty values. The only exception is the policy ID, which is immutable; it can only be set at creation time.

While you can use this endpoint to update members on a policy, if that is the only property you wish to modify you might find it more convenient to use one of these endpoints instead: Add policy members, Remove policy members, or Replace policy members.

Authorization Action:

iam:policies:update

path Parameters

id

required

string

Unique ID. Cannot be changed.

Request Body schema: application/json
required

id required	string Unique ID. Cannot be changed.
members	Array of strings Members affected by this policy.
name required	string Name for this policy.
projects	Array of strings List of projects this policy belongs to.
required	Array of objects (chef.automate.api.iam.v2.Statement) Statements for the policy.

Responses

Request samples

Payload
JSON

Content type

application/json

{"members": ["user:ldap:newuser",
"team:ldap:newteam"
],
"name": "My Updated Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Response samples

200
default

Content type

application/json

{"members": ["user:ldap:newuser",
"team:ldap:newteam"
],
"name": "My Updated Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Deletes a custom policy

Deletes a specified custom policy. You cannot delete Chef-managed policies.

Authorization Action:

iam:policies:delete

path Parameters

id

required

string

ID of the policy.

Responses

Response samples

200
default

Content type

application/json

{"id": "custom-viewer-policy",
"members": ["team:ldap:*"
],
"name": "My Viewer Policy",
"projects": [ ],
"statements": [{"effect": "ALLOW",
"projects": ["project1",
"project2"
],
"role": "viewer"
},
{"effect": "ALLOW",
"projects": ["acceptanceProject"
],
"role": "qa"
}
]
}

Lists policy members

Lists all members of a specific policy.

Authorization Action:

iam:policyMembers:get

path Parameters

id

required

string

ID of the policy.

Responses

Response samples

200
default

Content type

application/json

{"members": ["team:local:viewers",
"user:local:test"
]
}

Replaces policy members

Replaces the entire member list of a specific policy with a new list. You may use this endpoint to update members of either Custom or Chef-managed policies.

Ensure each element of the members array is in the correct Member Expression format.

Authorization Action:

iam:policyMembers:update

path Parameters

id

required

string

ID of the policy.

Request Body schema: application/json
required

id required	string ID of the policy.
members	Array of strings List of members that replaces previous policy member list.

Responses

Request samples

Payload
JSON

Content type

application/json

{"members": ["team:local:viewers",
"user:local:test"
]
}

Response samples

200
default

Content type

application/json

{"members": ["team:local:viewers",
"user:local:test"
]
}

Adds policy members

Adds members to the member list of a specific policy. You may use this endpoint to update members of either Custom or Chef-managed policies.

Ensure each element of the members array is in the correct Member Expression format.

Authorization Action:

iam:policyMembers:create

path Parameters

id

required

string

ID of the policy.

Request Body schema: application/json
required

id required	string ID of the policy.
members required	Array of strings List of members to add to the policy.

Responses

Request samples

Payload
JSON

Content type

application/json

{"members": ["team:local:viewers",
"user:local:test"
]
}

Response samples

200
default

Content type

application/json

{"members": ["team:local:viewers",
"user:local:test"
]
}

Removes policy members

Removes members from the member list of a specific policy. Silently ignores members that are not already part of the member list. You may use this endpoint to update members of either Custom or Chef-managed policies.

Ensure each element of the members array is in the correct Member Expression format.

The removed members will still exist within Chef Automate, but are no longer associated with this policy.

Authorization Action:

iam:policyMembers:delete

path Parameters

id

required

string

ID of the policy.

Request Body schema: application/json
required

id required	string ID of the policy.
members required	Array of strings List of members to remove from the policy.

Responses

Request samples

Payload
JSON

Content type

application/json

{"members": ["user:local:test"
]
}

Response samples

200
default

Content type

application/json

{"members": ["user:local:test"
]
}

Gets IAM version

Returns the major and minor version of IAM that your automate installation is running.

Authorization Action:

iam:policies:get

Responses

Response samples

200
default

Content type

application/json

{"version": {"major": "V2",
"minor": "V1"
}
}

IAM Roles

A role encapsulates a list of actions. Chef Automate provides several default Chef-managed roles that cannot be altered but you may also define and use your own Custom roles.

Lists all roles

Lists all Chef-managed and Custom roles.

Authorization Action:

iam:roles:list

Responses

Response samples

200
default

Content type

application/json

{"roles": [{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
},
{"actions": ["infra:*"
],
"id": "custom-role-2",
"name": "My Custom Secret Role 2"
}
]
}

Creates a custom role

Creates a new role to be used in the policies that control permissions in Automate.

A role defines the scope of actions in a policy statement.

Authorization Action:

iam:roles:create

Request Body schema: application/json
required

actions required	Array of strings List of actions that this role scopes to.
id required	string Unique ID. Cannot be changed.
name required	string Name for the role.
projects	Array of strings List of projects this role belongs to.

Responses

Request samples

Payload
JSON

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
}

Response samples

200
default

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
}

Gets a role

Returns the details for a role.

Authorization Action:

iam:roles:get

path Parameters

id

required

string

ID of the role.

Responses

Response samples

200
default

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
}

Updates a custom role

This operation overwrites all fields excepting ID, including those omitted from the request, so be sure to specify all properties. Properties that you do not include are reset to empty values.

Authorization Action:

iam:roles:update

path Parameters

id

required

string

Unique ID. Cannot be changed.

Request Body schema: application/json
required

actions required	Array of strings List of actions that this role scopes to.
id required	string Unique ID. Cannot be changed.
name required	string Name for the role.
projects	Array of strings List of projects this role belongs to.

Responses

Request samples

Payload
JSON

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"name": "My Updated Custom Secret Manager Role"
}

Response samples

200
default

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
}

Deletes a custom role

Deletes a specified custom role (you cannot delete Chef-managed roles) and remove it from any statements that may have been using it. If such a statement has no other associated actions, the statement is deleted as well. Similarly, if that statement removal results in a policy with no other statements, that policy is removed as well.

Authorization Action:

iam:roles:delete

path Parameters

id

required

string

ID of the role.

Responses

Response samples

200
default

Content type

application/json

{"actions": ["secrets:*",
"iam:projects:list"
],
"id": "custom-role",
"name": "My Custom Secret Manager Role"
}

IAM Projects

Projects are used to group and permission Chef Automate resources as well as ingested data, specifically Compliance reports, Chef Infra Server events, and Infrastructure nodes.

Lists all projects

Lists all projects.

Authorization Action:

iam:projects:list

Responses

Response samples

200
default

Content type

application/json

{"projects": [{"id": "custom-project",
"name": "My Custom Project"
},
{"id": "custom-project-2",
"name": "My Custom Project 2"
}
]
}

Creates a project

Creates a new project to be used in the policies that control permissions in Automate.

A project defines the scope of resources in a policy statement. Resources can be in more than one project.

When a project is created, the system also creates three policies associated with the new project, one for each of the following roles: editor, viewer, and project owner. You can optionally pass the skip_policies flag set to true to skip the creation of these policies.

Authorization Action:

iam:projects:create

Request Body schema: application/json
required

id required	string Unique ID. Cannot be changed.
name required	string Name for the new project.
skip_policies	boolean <boolean> Boolean flag to skip adding policies associated with the project. Set to false by default.

Responses

Request samples

Payload
JSON

Content type

application/json

{"id": "custom-project",
"name": "My Custom Project",
"skip_policies": true
}

Response samples

200
default

Content type

application/json

{"id": "custom-project",
"name": "My Custom Project"
}

Gets a project

Returns the details for a project.

Authorization Action:

iam:projects:get

path Parameters

id

required

string

ID of the project.

Responses

Response samples

200
default

Content type

application/json

{"id": "custom-project",
"name": "My Custom Project"
}

Updates a project

Updates the name of an existing project.

Authorization Action:

iam:projects:update

path Parameters

id

required

string

Unique ID. Cannot be changed.

Request Body schema: application/json
required

id required	string Unique ID. Cannot be changed.
name required	string Name for the project.

Responses

Request samples

Payload
JSON

Content type

application/json

{"name": "My Custom Project"
}

Response samples

200
default

Content type

application/json

{"id": "custom-project",
"name": "My Custom Project"
}

Deletes a project

Deletes a project from any resources tagged with it.

Also deletes this project from any project list in any policy statements. If the resulting project list for a given statement is empty, it is deleted. If the resulting policy has no statements, it is also deleted.

Authorization Action:

iam:projects:delete

path Parameters

id

required

string

ID of the project.

Responses

Response samples

200
default

Content type

application/json

{"id": "custom-project",
"name": "My Custom Project"
}

IAM Project Rules

Project rules define lists of one or more conditions that an ingested resource must meet in order to be assigned to a project.

Get the status of a project update

Returns details about a project update operation.

You can poll this endpoint during a project update to monitor progress. Querying this endpoint when there is no update in progress will return details about the completion status of the most recent update.

Authorization Action:

iam:rules:status

Responses

Response samples

200
default

Content type

application/json

{"cancelled": false,
"estimated_time_complete": "2020-03-20T19:24:55Z",
"failed": false,
"failure_message": "",
"percentage_complete": 0.5,
"state": "running"
}

Start project update

Any changes to a project's rules are staged first. They do not take effect until all projects are updated.

Updating all projects begins an operation that applies all pending rule edits and then moves ingested resources into the correct projects according to those latest changes.

With a large amount of historical compliance data, rule application can take a considerable amount of time. It’s best to batch up rule changes and apply them all at once.

Authorization Action:

iam:rules:apply

Responses

Response samples

200
default

Content type

application/json

{ }

Cancel project update

Cancels an ongoing project update.

Warning! This action leaves the system in an unknown state that only another successful project update can rectify.

This command exists really just for one scenario: you started a project update but shortly thereafter discovered that you had one more change to include in the batch of updates to be done.

Authorization Action:

iam:rules:cancel

Responses

Response samples

200
default

Content type

application/json

{ }

List a project's rules

Lists all of the project rules of a specific project.

Authorization Action:

iam:projects:get

path Parameters

id

required

string

ID of the project.

Responses

Response samples

200
default

Content type

application/json

{"rules": [{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "EQUALS",
"values": ["example.co"
]
}
],
"id": "example-rule",
"name": "My Applied Rule",
"project-id": "example-project",
"status": "APPLIED",
"type": "NODE"
},
{"conditions": [{"attribute": "CHEF_ORGANIZATION",
"operator": "MEMBER_OF",
"values": ["east",
"west"
]
}
],
"id": "example-rule-2",
"name": "My 2nd Example Rule",
"project-id": "example-project",
"status": "APPLIED",
"type": "EVENT"
}
],
"status": "APPLIED"
}

Create a project rule

Creates a new project rule to move ingested resources into projects.

A project rule contains conditions that determine if an ingested resource should be moved into the rule’s project.

Each condition specifies one or more values to match for a particular attribute on an ingested resource.

The choice of attributes depends on the rule type. For NODE type, specify any of the available attributes. For EVENT type, specify either CHEF_ORGANIZATION or CHEF_SERVER.

The choice of operator depends on how many values you provide. If you wish to match one among a group of values, set the operator to MEMBER_OF. For a single value, use EQUALS.

Authorization Action:

iam:projects:update

path Parameters

project_id

required

string

Unique ID of the project this rule belongs to. Cannot be changed.

Request Body schema: application/json
required

required	Array of objects (chef.automate.api.iam.v2.Condition) Conditions that ingested resources must match to belong to the project. Will contain one or more.
id required	string Unique ID. Cannot be changed.
name required	string Name for the project rule.
project_id required	string Unique ID of the project this rule belongs to. Cannot be changed.
type required	string (chef.automate.api.iam.v2.RuleType) Default: "RULE_TYPE_UNSET" Enum: "RULE_TYPE_UNSET" "NODE" "EVENT"

Responses

Request samples

Payload
JSON

Content type

application/json

{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "MEMBER_OF",
"values": ["example.co",
"example.io"
]
}
],
"id": "example-rule",
"name": "My Example Rule",
"project-id": "example-project",
"type": "NODE"
}

Response samples

200
default

Content type

application/json

{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "MEMBER_OF",
"values": ["example.co",
"example.io"
]
}
],
"id": "example-rule",
"name": "My Example Rule",
"project-id": "example-project",
"status": "STAGED",
"type": "NODE"
}

Get a project rule

Returns the details for a project rule.

Authorization Action:

iam:projects:get

path Parameters

project_id required	string ID of the project the rule belongs to.
id required	string ID of the project rule.

Responses

Response samples

200
default

Content type

application/json

{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "EQUALS",
"values": ["example.co"
]
}
],
"id": "example-rule",
"name": "My Applied Rule",
"project-id": "example-project",
"status": "APPLIED",
"type": "NODE"
}

Update a project rule

Updates the name and conditions of an existing project rule. New conditions can be added. Existing conditions can be updated or removed.

This operation overwrites all fields excluding ID and Type, including those omitted from the request, so be sure to specify all properties. Properties that you do not include are reset to empty values.

The resulting change to the project's resources does not take effect immediately. Updates to project rules must be applied to ingested resources by a project update.

Authorization Action:

iam:projects:update

path Parameters

project_id required	string Unique ID of the project this rule belongs to. Cannot be changed.
id required	string Unique ID. Cannot be changed.

Request Body schema: application/json
required

required	Array of objects (chef.automate.api.iam.v2.Condition) Conditions that ingested resources must match to belong to the project. Will contain one or more.
id required	string Unique ID. Cannot be changed.
name required	string Name for the project rule.
project_id required	string Unique ID of the project this rule belongs to. Cannot be changed.
type required	string (chef.automate.api.iam.v2.RuleType) Default: "RULE_TYPE_UNSET" Enum: "RULE_TYPE_UNSET" "NODE" "EVENT"

Responses

Request samples

Payload
JSON

Content type

application/json

{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "EQUALS",
"values": ["example.co"
]
}
],
"id": "example-rule",
"name": "My Updated Rule",
"project-id": "example-project",
"type": "NODE"
}

Response samples

200
default

Content type

application/json

{"conditions": [{"attribute": "CHEF_SERVER",
"operator": "EQUALS",
"values": ["example.co"
]
}
],
"id": "example-rule",
"name": "My Updated Rule",
"project-id": "example-project",
"status": "STAGED",
"type": "NODE"
}

Delete a project rule

The resulting change to the project's resources does not take effect immediately. Updates to project rules must be applied to ingested resources by a project update.

Authorization Action:

iam:projects:update

path Parameters

project_id required	string ID of the project the rule belongs to.
id required	string ID of the project rule.

Responses

Response samples

200
default

Content type

application/json

{ }

Chef Automate API Documentation (version not set)

Authentication

Status Codes

Reporting

List Controls

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Controls Search

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Export reports

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Export node reports

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Show Node Header Info From Report ID

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Show Node by ID

path Parameters

Responses

Response samples

List Nodes

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Profiles

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Report IDs

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Control Info

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Export reports

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Reports

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Show Report by ID

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List Reporting Suggestions

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Stats

Read Failures

Request Body schema: application/jsonrequired

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required