List Connectors - Cloud Security API

{"type":"api","title":"List Connectors","meta":{"id":"/apps/pubhub/media/cloud-security-apis-in-eft/9d37d008417d562ab46d4b67547a68457ce288d2/285f00e0-2a84-3aa5-a063-4c30a2b82db0","info":{"title":"Cisco Secure Access Resource Connector Groups and Resource Connectors API","description":"Manage the Resource Connector Groups and Resource Connectors in the organization.\n","version":"1.0.0","contact":{"name":"Cloud Security Developer Community"}},"security":[{"oauthFlow":[]}],"tags":[{"name":"Connector Groups","description":"Manage the Resource Connector Groups."},{"name":"Connectors","description":"Manage the Resource Connectors."},{"name":"Secure Access"}],"x-parser-conf":{"overview":{"markdownPath":"secure-access/reference/deployments/connector-groups-overview.md","uri":"secure-access-api-reference-connector-groups-overview"}},"openapi":"3.0.1","servers":[{"url":"https://api.sse.cisco.com/{basePath}","variables":{"basePath":{"default":"deployments/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"Client credential flow.","flows":{"clientCredentials":{"tokenUrl":"https://api.sse.cisco.com/auth/v2/token","scopes":{"deployments.resourceconnectors:read":"Read the Resource Connector Group or Connector resources","deployments.resourceconnectors:write":"Write the Resource Connector Group or Connector resources"}}}}}},"spec":{"tags":["Connectors","Secure Access"],"summary":"List Connectors","description":"List the Connectors for the Resouce Connector Groups in the organization.\nIf you include query filters on the request, the response is a subset of the Connectors in the organization.","operationId":"listConnectors","security":[{"oauthFlow":["deployments.resourceconnectors:read"]}],"parameters":[{"name":"filters","in":"query","required":false,"description":"Filter the list of Connectors by one or more properties.\n\nFor example:\n\n```\n{\n \"groupId\": \"123\",\n \"instanceId\": \"i-04568b6cdaeedda25a\",\n \"status\": \"connected,reachable\",\n \"confirmed\": true\n}\n```\n\nFilters are applied to the following properties:\n\n* **groupId**—A comma-separated list of Connector Group IDs.\n* **instanceId**—The ID of the Connector. The value is not case sensitive.\n* **status**—A comma-separated list of Connector status labels.\n* **confirmed**—If set to `true`, list the confirmed location of the Connector. The value is not case sensitive.\n* **hasSynced**—If set to `true`, list the Connectors that have successfully synced.\n* **hasLatestVersion**—If set to `true`, list the Connectors that have the latest software version.","schema":{"type":"string"},"$$ref":"#/components/parameters/filtersConnectorAgents"},{"name":"offset","in":"query","required":false,"description":"The place to start reading in the collection. The offset starts at 0.\nIf the `limit` is 10, the offset for the next response is 10. The default value is 0.","schema":{"type":"integer","default":0},"example":25,"$$ref":"#/components/parameters/offset"},{"name":"limit","in":"query","required":false,"description":"The maximum number of items to return in the response from the collection. The default value is 10.","schema":{"type":"integer","default":10},"example":100,"$$ref":"#/components/parameters/limit"},{"name":"sortBy","in":"query","required":false,"description":"Specify a field to filter the collection.","schema":{"type":"string","enum":["instanceId","originIpAddress","createdAt","modifiedAt"],"default":"originIpAddress"},"example":"originIpAddress","$$ref":"#/components/parameters/sortByConnectorAgent"},{"name":"sortOrder","in":"query","required":false,"description":"Specify a field in the response to order the collection.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"example":"desc","$$ref":"#/components/parameters/sortOrder"}],"responses":{"200":{"description":"OK","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","description":"The properties of the Connectors.","properties":{"data":{"description":"The list of Connectors and metadata about the Connectors.","type":"array","items":{"type":"object","description":"Get the details about the Connector.","properties":{"id":{"type":"integer","description":"The ID of the Connector.","readOnly":true,"example":123456,"$$ref":"#/components/schemas/idConnector"},"groupId":{"description":"The ID of the Resource Connector Group.","type":"integer","readOnly":true,"example":1234557,"$$ref":"#/components/schemas/idConnectorGroup"},"instanceId":{"type":"string","description":"The globally unique ID of the Connector instance.","example":"i-04568b6cdaeedda25a"},"confirmed":{"type":"boolean","description":"Indicates whether the Connector exists.","default":false,"example":true},"enabled":{"type":"boolean","description":"Indicates whether the Connector can receive traffic.","default":false,"example":true},"version":{"type":"string","description":"The runtime version of the Connector image.","readOnly":true,"example":"v10.1"},"sha1":{"type":"string","description":"The unique ID of the Connector formatted as a hash string.","example":"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"},"hostname":{"type":"string","description":"The unique hostname of the device that manages the runtime of the Connector.","example":"i-0123456789abcdef.us-west-2.compute.internal"},"originIpAddress":{"type":"string","description":"The IP address of the Connector.","readOnly":true,"example":"10.45.102.214"},"baseVersion":{"type":"string","description":"The base OS version of the Connector image.\nUpdating the base OS version requires that you download and redeploy the latest Connector image.","readOnly":true,"example":"240127"},"isLatestBaseVersion":{"type":"boolean","description":"Indicates whether the Connector is using the latest available image.\nIf this value is false, a new image is available to download. We recommend that you redeploy this Connector with the latest image.","readOnly":true,"example":true},"upgradeStatus":{"type":"string","description":"Indicates the status of the latest over-the-air update for this Connector.\nOver-the-air updates modify the Connector agent software, which are made without downloading a new image and redeploying the Connector.","enum":["successful","in_progress","failed","unknown"],"readOnly":true,"example":"successful"},"status":{"type":"string","description":"The label that describes the status of the Connector.","enum":["disconnected","connected","announced","reachable","disabled"],"readOnly":true,"default":"announced"},"statusUpdatedAt":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time when the Connector was updated, specified in the ISO 8601 format.","example":"2023-03-14T18:34:25.412525046Z"},"controlStatusUpdatedAt":{"type":"string","description":"The date and time when the Connector's controller status was last updated, specified in the ISO 8601 format.","format":"date-time","readOnly":true,"example":"2023-03-15T01:22:45.915326851Z"},"revoked_at":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time when the Connector was removed, specified in the ISO 8601 format.","example":"2023-03-14T18:34:25.412525046Z"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time when the Connector was created, specified in the ISO 8601 format.","example":"2023-03-14T18:34:25.412525046Z"},"modifiedAt":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time when the Connector was last modified, specified in the ISO 8601 format.","example":"2023-03-14T18:34:25.412525046Z"}},"example":{"id":123456,"groupId":123964,"instanceId":"i-04568b6cdaeedda25a","confirmed":true,"enabled":true,"version":"v10.1","sha1":"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed","hostname":"i-0123456789abcdef.us-west-2.compute.internal","originIpAddress":"10.45.102.214","status":"connected","statusUpdatedAt":"2023-03-14T18:34:25.412525046Z","revoked_at":"2023-03-14T18:34:25.412525046Z","createdAt":"2023-03-14T18:34:25.412525046Z","modifiedAt":"2023-03-14T18:34:25.412525046Z","baseVersion":"240127","isLatestBaseVersion":true,"upgradeStatus":"successful"},"$$ref":"#/components/schemas/connectorResponse"}},"offset":{"description":"The place to start reading in the collection. The offset starts at 0.\nIf the `limit` is 10, the offset for the next response is 10. The default value is 0.","type":"integer","default":0,"example":1000,"$$ref":"#/components/schemas/offset"},"limit":{"description":"The maximum number of items in the response.","type":"integer","example":100,"$$ref":"#/components/schemas/limit"},"total":{"description":"The total number of items read from the collection.","type":"integer","example":2000,"$$ref":"#/components/schemas/total"}},"example":{"data":[{"id":123456,"groupId":123964,"instanceId":"i-04568b6cdaeedda25a","confirmed":true,"enabled":true,"version":"v10.1","sha1":"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed","hostname":"i-0123456789abcdef.us-west-2.compute.internal","originIpAddress":"10.45.102.214","status":"connected","statusUpdatedAt":"2023-03-14T18:34:25.412525046Z","revoked_at":"2023-03-14T18:34:25.412525046Z","createdAt":"2023-03-14T18:34:25.412525046Z","modifiedAt":"2023-03-14T18:34:25.412525046Z","baseVersion":"240127","isLatestBaseVersion":true,"upgradeStatus":"successful"}],"offset":1,"limit":50,"total":100},"$$ref":"#/components/schemas/connectorListRes"},"example":{"data":[{"id":123456,"groupId":123964,"instanceId":"i-04568b6cdaeedda25a","confirmed":true,"enabled":true,"version":"v10.1","sha1":"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed","hostname":"i-0123456789abcdef.us-west-2.compute.internal","originIpAddress":"10.45.102.214","status":"connected","statusUpdatedAt":"2023-03-14T18:34:25.412525046Z","revoked_at":"2023-03-14T18:34:25.412525046Z","createdAt":"2023-03-14T18:34:25.412525046Z","modifiedAt":"2023-03-14T18:34:25.412525046Z"}],"offset":1,"limit":50,"total":100}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"The organization ID is a numeric value."},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}}}},"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"$$ref":"#/components/responses/400Error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Authorization token is invalid."},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}}}},"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"$$ref":"#/components/responses/401Error"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Not Authorized"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}}}},"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"$$ref":"#/components/responses/403Error"},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Internal Server Error"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}}}},"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"$$ref":"#/components/responses/500Error"}},"__originalOperationId":"listConnectors","method":"get","path":"/connectorAgents"}}