SupportSnyk LearnAPI referenceProduct updatesSign up for free

Cloud

This document uses the REST API. For more details, see the Authentication for API page.

Create Scan (Early Access)

post

Create and trigger a new scan for an environment

Required permissions

  • Create scans (org.cloud_scans.create)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Body
Responses
201

Created scan successfully

application/vnd.api+json
post
POST /rest/orgs/{org_id}/cloud/scans HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 148

{
  "data": {
    "attributes": {},
    "relationships": {
      "environment": {
        "data": {
          "id": "12000000-0000-0000-0000-000000000000",
          "type": "environment"
        }
      }
    },
    "type": "scan"
  }
}
{
  "data": {
    "attributes": {
      "created_at": "2022-05-06T12:25:15-04:00",
      "error": "",
      "finished_at": "2022-05-06T12:25:15-04:00",
      "kind": "user_initiated",
      "options": {
        "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
      },
      "revision": 1,
      "status": "success",
      "updated_at": "2022-05-06T12:25:15-04:00"
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "relationships": {
      "environment": {
        "data": {
          "id": "12000000-0000-0000-0000-000000000000",
          "type": "environment"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      },
      "organization": {
        "data": {
          "id": "10000000-0000-0000-0000-000000000000",
          "type": "organization"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      }
    },
    "type": "scan"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

List Scans (Early Access)

get

List scans for an organization

Required permissions

  • View scans (org.cloud_scans.read)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
starting_afterstringOptional

Return the page of results immediately after this cursor

Example: v1.eyJpZCI6IjEwMDAifQo=
ending_beforestringOptional

Return the page of results immediately before this cursor

Example: v1.eyJpZCI6IjExMDAifQo=
limitinteger · int32 · min: 10 · max: 100Optional

Number of results to return per page

Default: 10Example: 10
Responses
200

Returns a list of scan instances

application/vnd.api+json
get
GET /rest/orgs/{org_id}/cloud/scans HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "attributes": {
        "created_at": "2022-05-06T12:25:15-04:00",
        "error": "",
        "finished_at": "2022-05-06T12:25:15-04:00",
        "kind": "user_initiated",
        "options": {
          "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
        },
        "revision": 1,
        "status": "success",
        "updated_at": "2022-05-06T12:25:15-04:00"
      },
      "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
      "relationships": {
        "environment": {
          "data": {
            "id": "12000000-0000-0000-0000-000000000000",
            "type": "environment"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        },
        "organization": {
          "data": {
            "id": "10000000-0000-0000-0000-000000000000",
            "type": "organization"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        }
      },
      "type": "scan"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

Get scan (Early Access)

get

Get a single scan for an organization

Required permissions

  • View scans (org.cloud_scans.read)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
scan_idstring · uuidRequired

Scan ID

Example: 56465b1d-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Responses
200

Returns a single scan instance

application/vnd.api+json
get
GET /rest/orgs/{org_id}/cloud/scans/{scan_id} HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "attributes": {
      "created_at": "2022-05-06T12:25:15-04:00",
      "error": "",
      "finished_at": "2022-05-06T12:25:15-04:00",
      "kind": "user_initiated",
      "options": {
        "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
      },
      "revision": 1,
      "status": "success",
      "updated_at": "2022-05-06T12:25:15-04:00"
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "relationships": {
      "environment": {
        "data": {
          "id": "12000000-0000-0000-0000-000000000000",
          "type": "environment"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      },
      "organization": {
        "data": {
          "id": "10000000-0000-0000-0000-000000000000",
          "type": "organization"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      }
    },
    "type": "scan"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

List Resources (Early Access)

get

List resources for an organization

Required permissions

  • View resources (org.cloud_resources.read)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
environment_idstring · uuidOptional

Filter resources by environment ID (multi-value, comma-separated)

Example: 052781a7-17f6-494d-0000-25c8b509abcd
resource_typestringOptional

Filter resources by resource type (multi-value, comma-separated)

Example: aws_s3_bucket
resource_idstringOptional

Filter resources by resource ID (multi-value, comma-separated)

Example: example-bucket
native_idstringOptional

Filter resources by native ID (multi-value, comma-separated) (AWS ARN)

Example: arn:aws:s3:::example-bucket
idstringOptional

Filter resources by resource UUID (multi-value, comma-separated)

Example: 4a662442-7445-55c3-adcc-cbbbdd99999
platformstringOptional

Filter resources by platform (multi-value, comma-separated): aws

Example: aws
namestringOptional

Filter resources by name (multi-value, comma-separated)

Example: example-bucket
kindstringOptional

Kind of resource: cloud

Example: cloud - cloud - iac
locationstringOptional

Filter resources by location (multi-value, comma-separated) (AWS region)

Example: us-west-2
removedbooleanOptional

Filter resources by whether they have been removed or not.

Example: true
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
starting_afterstringOptional

Return the page of results immediately after this cursor

Example: v1.eyJpZCI6IjEwMDAifQo=
ending_beforestringOptional

Return the page of results immediately before this cursor

Example: v1.eyJpZCI6IjExMDAifQo=
limitinteger · int32 · min: 10 · max: 100Optional

Number of results to return per page

Default: 10Example: 10
Responses
200

Returns a list of resources

application/vnd.api+json
get
GET /rest/orgs/{org_id}/cloud/resources HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "attributes": {
        "created_at": "2022-08-10T17:19:33.14749Z",
        "hash": "3333342563a86c675333de5848c9220a7bb35c039e7b9c0688c10f72b4666666",
        "kind": "runtime",
        "location": "us-west-2",
        "name": "example-bucket",
        "namespace": "us-west-2",
        "native_id": "arn:aws:s3:::example-bucket",
        "options": "json here",
        "origin": "aws-account",
        "platform": "aws",
        "resource_id": "example-bucket",
        "resource_type": "aws_s3_bucket",
        "revision": 1,
        "state": {
          "acl": "private",
          "arn": "arn:aws:s3:::example-bucket",
          "bucket": "example-bucket"
        },
        "tags": {
          "stage": "prod"
        },
        "updated_at": "2022-08-10T17:19:33.14749Z"
      },
      "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
      "relationships": {
        "environment": {
          "data": {
            "id": "11000000-0000-0000-0000-000000000000",
            "type": "environment"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        },
        "organization": {
          "data": {
            "id": "10000000-0000-0000-0000-000000000000",
            "type": "organization"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        },
        "scan": {
          "data": {
            "id": "12000000-0000-0000-0000-000000000000",
            "type": "scan"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        }
      },
      "type": "resource"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

Generate Cloud Provider Permissions (Early Access)

post

Generate IAC template for Snyk to access your cloud resources

Required permissions

  • Create environments (org.cloud_environments.create)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Body
Responses
201

Created permissions successfully

application/vnd.api+json
post
POST /rest/orgs/{org_id}/cloud/permissions HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 74

{
  "data": {
    "attributes": {
      "platform": "aws",
      "type": "cf"
    },
    "type": "permission"
  }
}
{
  "data": {
    "attributes": {
      "data": "text",
      "type": "cf"
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "type": "permission"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

Create New Environment (Early Access)

post

Create a new environment and run a scan

Required permissions

  • Create environments (org.cloud_environments.create)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Body
Responses
201

Created environment successfully

application/vnd.api+json
post
POST /rest/orgs/{org_id}/cloud/environments HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 129

{
  "data": {
    "attributes": {
      "kind": "aws",
      "options": {
        "role_arn": "arn:aws:iam::336447867772:role/SnykCloud1234"
      }
    },
    "type": "environment"
  }
}
{
  "data": {
    "attributes": {
      "created_at": "2022-05-06T12:25:15-04:00",
      "kind": "aws",
      "name": "Demo AWS Environment",
      "native_id": "12345678910",
      "options": {
        "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
      },
      "properties": {
        "account_id": "123456789012"
      },
      "revision": 1,
      "status": "success",
      "updated_at": "2022-05-06T12:25:15-04:00"
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "relationships": {
      "organization": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "organization"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      },
      "project": {
        "data": {
          "id": "11111111-1111-11111-1111-111111111111",
          "type": "project"
        }
      }
    },
    "type": "environment"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

List Environments (Early Access)

get

List environments for an organization

Required permissions

  • View environments (org.cloud_environments.read)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
created_afterstring · date-timeOptional

Return environments created after this date

Example: 2022-05-06T12:25:15-04:00
created_beforestring · date-timeOptional

Return environments created before this date

Example: 2022-05-06T12:25:15-04:00
updated_afterstring · date-timeOptional

Return environments updated after this date

Example: 2022-05-06T12:25:15-04:00
updated_beforestring · date-timeOptional

Return environments updated before this date

Example: 2022-05-06T12:25:15-04:00
namestringOptional

Environment name

Example: Demo AWS Environment
kindstring · enumOptional

Environment kind: aws

Example: awsPossible values:
statusstring · enumOptional

Filter environments by latest scan status (multi-value, comma-separated)

Example: errorPossible values:
idstring · uuidOptional

Filter environments by environment ID (multi-value, comma-separated)

Example: 052781a7-17f6-494d-0000-25c8b509abcd
project_idstring · uuidOptional

Filter environments by project ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
starting_afterstringOptional

Return the page of results immediately after this cursor

Example: v1.eyJpZCI6IjEwMDAifQo=
ending_beforestringOptional

Return the page of results immediately before this cursor

Example: v1.eyJpZCI6IjExMDAifQo=
limitinteger · int32 · min: 10 · max: 100Optional

Number of results to return per page

Default: 10Example: 10
Responses
200

Returns a list of environments

application/vnd.api+json
get
GET /rest/orgs/{org_id}/cloud/environments HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "attributes": {
        "created_at": "2022-05-06T12:25:15-04:00",
        "kind": "aws",
        "name": "Demo AWS Environment",
        "native_id": "12345678910",
        "options": {
          "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
        },
        "properties": {
          "account_id": "123456789012"
        },
        "revision": 1,
        "status": "success",
        "updated_at": "2022-05-06T12:25:15-04:00"
      },
      "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
      "relationships": {
        "organization": {
          "data": {
            "id": "00000000-0000-0000-0000-000000000000",
            "type": "organization"
          },
          "links": {
            "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
          }
        },
        "project": {
          "data": {
            "id": "11111111-1111-11111-1111-111111111111",
            "type": "project"
          }
        }
      },
      "type": "environment"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

Update Environment (Early Access)

patch

Update an environment

Required permissions

  • Update environments (org.cloud_environments.edit)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
environment_idstring · uuidRequired

Unique identifier for an environment

Example: 052781a7-17f6-494d-0000-25c8b509abcd
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Body
Responses
200

Updated an environment successfully

application/vnd.api+json
patch
PATCH /rest/orgs/{org_id}/cloud/environments/{environment_id} HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 160

{
  "data": {
    "attributes": {
      "options": {
        "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
      }
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "type": "environment"
  }
}
{
  "data": {
    "attributes": {
      "created_at": "2022-05-06T12:25:15-04:00",
      "kind": "aws",
      "name": "Demo AWS Environment",
      "native_id": "12345678910",
      "options": {
        "role_arn": "arn:aws:iam::123456789012:role/SnykCloud1234"
      },
      "properties": {
        "account_id": "123456789012"
      },
      "revision": 1,
      "status": "success",
      "updated_at": "2022-05-06T12:25:15-04:00"
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "relationships": {
      "organization": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "organization"
        },
        "links": {
          "related": "/path/to/<related resource>/<related-id>?version=<resolved version>&..."
        }
      },
      "project": {
        "data": {
          "id": "11111111-1111-11111-1111-111111111111",
          "type": "project"
        }
      }
    },
    "type": "environment"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  }
}

Delete Environment (Early Access)

delete

Delete an environment

Required permissions

  • Delete environments (org.cloud_environments.delete)
Authorizations
Path parameters
org_idstring · uuidRequired

Organization ID

Example: 9a46d918-8764-458c-1234-0987abcd6543
environment_idstring · uuidRequired

Unique identifier for an environment

Example: 052781a7-17f6-494d-0000-25c8b509abcd
Query parameters
versionstringRequired

Requested API version

Example: 2021-06-04Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$
Responses
204

Returns an empty response

delete
DELETE /rest/orgs/{org_id}/cloud/environments/{environment_id} HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

No content
PreviousAudit LogsNextCollection

Last updated

Was this helpful?