Search REST API Examples

The first step in using the Search API is to generate an IAM token. You can generate the IAM Token using the IAM API and your IBM Cloud API key.
export IBMCLOUD_API_KEY=<Your IBM Cloud API Key>
​
iam_token=`curl -s -k -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
--data-urlencode "apikey=${IBMCLOUD_API_KEY}" "https://iam.cloud.ibm.com/identity/token"  | jq -r '(.token_type + " " + .access_token)'`
List all supported resource types
Retrieves a list of all the resource types supported by the Cloud and Classic infrastructure global catalog.
curl -s -X GET https://api.global-search-tagging.cloud.ibm.com/v2/resources/supported_types -H "authorization: ${iam_token}" | jq -r
{
  "supported_types": [
    "resource-instance",
    "resource-instance-provision-behind",
    "resource-group",
    "resource-binding",
    "resource-alias",
    "k8-cluster",
    "k8-location",
    "is-vpc",
    "is-instance",
    "is-key",
    "is-volume",
    "is-load-balancer",
    "is-vpn",
    "is-image",
    "is-security-group",
    "is-subnet",
    "is-public-gateway",
    "is-floating-ip",
    "is-network-acl",
    "is-endpoint-gateway",
    "is-flow-log-collector",
    "is-instance-group",
    "is-dedicated-host",
    "is-family",
    "cf-user-provided-service-instance",
    "cf-space",
    "cf-service-instance",
    "cf-service-binding",
    "cf-organization",
    "cf-application",
    "vmware-solutions",
    "ims-block-storage",
    "ims-cloud-backup",
    "ims-cloud-object-storage-infrastructure",
    "ims-file-storage",
    "ims-cdn-powered-by-akamai",
    "ims-direct-link-cloud-connect",
    "ims-direct-link-cloud-exchange",
    "ims-direct-link-colocation",
    "ims-direct-link-network-service-provider",
    "ims-hardware-firewall",
    "ims-hardware-firewall-dedicated",
    "ims-fortigate-security-appliance-1gb",
    "ims-fortigate-security-appliance-10gb",
    "ims-network-gateway-juniper-vsrx",
    "ims-network-gateway-byoa",
    "ims-virtual-router-appliance-copy",
    "ims-ibm-cloud-load-balancer",
    "ims-bare-metal",
    "ims-virtual-server",
    "ims-dedicated-host",
    "ims-image",
    "activity-insights",
    "network-insights",
    "security-advisor"
  ]
}
Classic IaaS Resource Examples
Find Classic IaaS virtual instances by tag:
In order to search for resources on your account you need to supply your Account ID. From a terminal you can run the command ibmcloud account show to grab the Account ID. In this example I am searching for all IaaS instances with the tag consul
$ export ACCOUNT_ID=<Your IBM Account ID>
​
$ curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" \ 
-H "content-type: application/json" -H "accept: application/json" -H \ 
"Authorization: ${iam_token}" -d '{"query":"(type:virtual-server AND family:ims) AND (tags:consul)"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "consul-server3.cdetesting.com",
      "type": "virtual-server",
      "family": "ims",
      "crn": "crn:v1:bluemix:public:virtual-server:wdc06:a/xxxxxxxxxxxxxxxxxxxxxx:90725760::"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "consul-server2.cdetesting.com",
      "type": "virtual-server",
      "family": "ims",
      "crn": "crn:v1:bluemix:public:virtual-server:wdc06:a/xxxxxxxxxxxxxxxxxxxxxx:90725768::"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "consul-server1.cdetesting.com",
      "type": "virtual-server",
      "family": "ims",
      "crn": "crn:v1:bluemix:public:virtual-server:wdc06:a/xxxxxxxxxxxxxxxxxxxxxx:90725770::"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxx"
}
Find Block storage volumes with specific note
The Classic File and Block volumes do not support tagging via the Cloud Portal. In their place their is a field to store notes about the volume. We will run a search for all block volumes with the note ryantiffany and just return their names. You can tag these volumes via the Tagging API. For an example of how to tag Block / File storage see the following example.
$ curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?limit=50" \ 
-H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" \ 
-d '{"query":"(type:block-storage AND service_name:block-storage) AND (doc.notes:ryantiffany)" , "fields": [ "name", "tags" ]}' | jq -r
{
  "items": [
    {
      "name": "SL02SEL78003-13",
      "crn": "crn:v1:bluemix:public:block-storage:wdc07:a/xxxxxxxxxxxxxxxxxxxxxx:53093855::",
      "tags": []
    }
  ],
  "limit": 50,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Find all VMware Solutions deployments
The following call with return all the VMware Dedicated and VMware Shared deployments on the account.
curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" -d '{"query":"type:vmware-solutions"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "vcs-rt",
      "type": "vmware-solutions",
      "family": "vmware",
      "crn": "crn:v1:bluemix:public:vmware-solutions:global:a/xxxxxxxxxxxxxxxxxxxxxx:55c17e7d-eaed-4b4f-xxxx-xxxxxxxx::"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "primary-rt",
      "type": "vmware-solutions",
      "family": "vmware",
      "crn": "crn:v1:bluemix:public:vmware-solutions:global:a/xxxxxxxxxxxxxxxxxxxxxx:707319d9-2f6b-4b48-xxxx-xxxxxxxx::"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "jb-test-1",
      "type": "vmware-solutions",
      "family": "vmware",
      "crn": "crn:v1:bluemix:public:vmware-solutions:global:a/xxxxxxxxxxxxxxxxxxxxxx:824912d4-10be-4421-xxxx-xxxxxxxx::"
    },
    {
      "account_id": "6c27214690345bfb75bb1f2b28a20504",
      "name": "centerpoint",
      "type": "vmware-solutions",
      "family": "vmware",
      "crn": "crn:v1:bluemix:public:vmware-solutions:global:a/6c27214690345bfb75bb1f2b28a20504:900d7d94-8236-4382-xxxx-xxxxxxxx:"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "vcd-rt",
      "type": "vmware-solutions",
      "family": "vmware",
      "crn": "crn:v1:bluemix:public:vmware-solutions:global:a/xxxxxxxxxxxxxxxxxxxxxx:9ac98b37-cd31-4800-xxxx-xxxxxxxx::"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Find all Juniper Network Gateway appliances in the Washington 7 Datacenter
curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" -d '{"query":"(family:ims AND type:network-gateway-juniper-vsrx) AND (region:washington-7)"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "ha-srx",
      "type": "network-gateway-juniper-vsrx",
      "family": "ims",
      "crn": "crn:v1:bluemix:public:network-gateway-juniper-vsrx:washington-7:a/xxxxxxxxxxxxxxxxxxxxxx:538282::"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Cloud Resources
Find all Kubernetes Clusters and just return their name and associated tags:
Note: the CRN is always returned even if not part of the field return parameters.
curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "content-type: application/json" -H "accept: application/json" -H "Authorization: ${iam_token}" -d '{"query": "type:k8-cluster", "fields": [ "name", "tags", "service_instance" ]}' | jq -r
{
  "items": [
    {
      "name": "devcluster",
      "service_instance": "bpdhxxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:bpdhxxxx::",
      "tags": [
        "ryantiffany"
      ]
    },
    {
      "name": "mycluster-dal10-b3c.4x16",
      "service_instance": "bsdexxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:bsdexxxx::",
      "tags": [
        "jack"
      ]
    },
    {
      "name": "aamir-testcluster-sjc04-b3c.4x16",
      "service_instance": "bslaxxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:bslaxxxx::",
      "tags": []
    },
    {
      "name": "cluster2",
      "service_instance": "btckxxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:btckxxxx::",
      "tags": []
    },
    {
      "name": "Russell_Cluster",
      "service_instance": "bthrxxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:bthrxxxx::",
      "tags": []
    },
    {
      "name": "rt-us-south",
      "service_instance": "btr2xxxx",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:btr2xxxx::",
      "tags": [
        "region:us-south",
        "ryantiffany"
      ]
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Find all Kubernetes clusters in a given region
In this example we are searching for all Kubernetes Clusters in the Tokyo region:
$ curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" -d '{"query":"type:k8-cluster AND region:jp-tok"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "subredOpen",
      "type": "k8-cluster",
      "family": "containers",
      "crn": "crn:v1:bluemix:public:containers-kubernetes:jp-tok:a/xxxxxxxxxxxxxxxxxxxxxx:blr1xxxxxx:"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Find all VPC instances in a specific region with specific tags
Since VPC instances stretch across multiple zones in a region we use the wildcard search term region:us-east* in this case to show all instances within the US-East VPC region.
$ curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" -d '{"query":"(family:is AND type:instance AND region:us-east*)"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "wgtest-z1-dev",
      "type": "instance",
      "family": "is",
      "crn": "crn:v1:bluemix:public:is:us-east-1:a/xxxxxxxxxxxxxxxxxxxxxx::instance:0757_2834694d-ad33-4b81-xxxx-xxxxxxxx"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "wgtest-wg-dev",
      "type": "instance",
      "family": "is",
      "crn": "crn:v1:bluemix:public:is:us-east-1:a/xxxxxxxxxxxxxxxxxxxxxx::instance:0757_ebdfe595-c96b-4924-xxxx-xxxxxxxx"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "vpntest",
      "type": "instance",
      "family": "is",
      "crn": "crn:v1:bluemix:public:is:us-east-1:a/xxxxxxxxxxxxxxxxxxxxxx::instance:0757_f89fa662-71ab-45e1-xxxx-xxxxxxxx"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "wgtest-z2-dev",
      "type": "instance",
      "family": "is",
      "crn": "crn:v1:bluemix:public:is:us-east-2:a/xxxxxxxxxxxxxxxxxxxxxx::instance:0767_65809d72-adca-4c5d-xxxx-xxxxxxxx"
    },
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "wgtest-z3-dev",
      "type": "instance",
      "family": "is",
      "crn": "crn:v1:bluemix:public:is:us-east-3:a/xxxxxxxxxxxxxxxxxxxxxx::instance:0777_e7321492-179b-4f26-xxxx-xxxxxxxx"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
Find all Database for Etcd instances with a specific tag
curl -s -X POST "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=${ACCOUNT_ID}" -H "accept: application/json" -H "Authorization: ${iam_token}" -H "content-type: application/json" -d '{"query":"(type:resource-instance AND service_name:databases-for-etcd) AND (tags:ryantiffany)"}' | jq -r
{
  "items": [
    {
      "account_id": "xxxxxxxxxxxxxxxxxxxxxx",
      "name": "rt-1978903720bf",
      "type": "resource-instance",
      "family": "resource_controller",
      "crn": "crn:v1:bluemix:public:databases-for-etcd:us-south:a/xxxxxxxxxxxxxxxxxxxxxx:41625c25-f836-491e-xxx-xxxxxx::"
    }
  ],
  "limit": 10,
  "search_cursor": "xxxxxxxxxxxxxxxxxxxxxx"
}
IBM Virtual Private Cloud - Previous
Site to Site IPsec with VPC VPNaaS
Next - IBM Cloud Search and Tagging Examples
Tagging REST API Examples
Last modified 1yr ago
Copy link
Outline
List all supported resource types
Classic IaaS Resource Examples
Find Classic IaaS virtual instances by tag:
Find Block storage volumes with specific note
Find all VMware Solutions deployments
Find all Juniper Network Gateway appliances in the Washington 7 Datacenter
Cloud Resources
Find all Kubernetes Clusters and just return their name and associated tags:
Find all Kubernetes clusters in a given region
Find all VPC instances in a specific region with specific tags
Find all Database for Etcd instances with a specific tag